Manuale PHP

classkit_method_add

(PECL)

classkit_method_add -- Dynamically adds a new method to a given class

Descrizione

bool classkit_method_add ( string classname, string methodname, string args, string code [, int flags] )

Avvertimento

Elenco dei parametri

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 methodname is called
flags: The type of method to create, can be CLASSKIT_ACC_PUBLIC, CLASSKIT_ACC_PROTECTED or CLASSKIT_ACC_PRIVATE
Nota: This parameter is only used as of PHP 5, because, prior to this, all methods were public.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 1. classkit_method_add() example
<?php class Example { function foo() { echo "foo!\n"; } } // create an Example object $e = new Example(); // Add a new public method classkit_method_add( 'Example', 'add', '$num1, $num2', 'return $num1 + $num2;', CLASSKIT_ACC_PUBLIC ); // add 12 + 4 echo $e->add(12, 4); ?>
Il precedente esempio visualizzerà:
16

Vedere anche:

create_function()

classkit_method_copy

(PECL)

classkit_method_copy -- Copies a method from class to another

Descrizione

bool classkit_method_copy ( string dClass, string dMethod, string sClass [, string sMethod] )

Avvertimento

Elenco dei parametri

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 dMethod is assumed.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 1. classkit_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() classkit_method_copy('Bar', 'baz', 'Foo', 'example'); // output copied function echo Bar::baz(); ?>
Il precedente esempio visualizzerà:
foo!

Vedere anche:

classkit_method_redefine

(PECL)

classkit_method_redefine -- Dynamically changes the code of the given method

Descrizione

bool classkit_method_redefine ( string classname, string methodname, string args, string code [, int flags] )

Nota: This function cannot be used to manipulate the currently running (or chained) method.

Avvertimento

Elenco dei parametri

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 methodname is called
flags: The redefined method can be CLASSKIT_ACC_PUBLIC, CLASSKIT_ACC_PROTECTED or CLASSKIT_ACC_PRIVATE
Nota: This parameter is only used as of PHP 5, because, prior to this, all methods were public.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 1. classkit_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 classkit_method_redefine( 'Example', 'foo', '', 'return "bar!\n";', CLASSKIT_ACC_PUBLIC ); // output Example::foo() (after redefine) echo "After: " . $e->foo(); ?>
Il precedente esempio visualizzerà:
Before: foo! After: bar!

Vedere anche:

classkit_method_remove

(PECL)

classkit_method_remove -- Dynamically removes the given method

Descrizione

bool classkit_method_remove ( string classname, string methodname )

Nota: This function cannot be used to manipulate the currently running (or chained) method.

Avvertimento

Elenco dei parametri

classname: The class in which to remove the method
methodname: The name of the method to remove

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 1. classkit_method_remove() example
<?php class Example { function foo() { return "foo!\n"; } function bar() { return "bar!\n"; } } // Remove the 'foo' method classkit_method_remove( 'Example', 'foo' ); echo implode(' ', get_class_methods('Example')); ?>
Il precedente esempio visualizzerà:
bar

Vedere anche:

classkit_method_rename

(PECL)

classkit_method_rename -- Dynamically changes the name of the given method

Descrizione

bool classkit_method_rename ( string classname, string methodname, string newname )

Nota: This function cannot be used to manipulate the currently running (or chained) method.

Avvertimento

Elenco dei parametri

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

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 1. classkit_method_rename() example
<?php class Example { function foo() { return "foo!\n"; } } // Rename the 'foo' method to 'bar' classkit_method_rename( 'Example', 'foo', 'bar' ); // output renamed function echo Example::bar(); ?>
Il precedente esempio visualizzerà:
foo!

Vedere anche:

XIV. Funzioni ClibPDF

Introduzione

ClibPDF permette di creare documenti PDF utilizzando PHP. La funzionalità e l' API di ClibPDF sono simili a quelle di PDFlib. Questa documentazione dovrebbe essere letta insieme al manuale di ClibPDF poichè entra maggiormente nel dettaglio della libreria.

Molte funzioni nella ClibPDF nativa e nel modulo PHP , così come nella PDFlib hanno lo stesso nome. Tutte le funzioni ad eccezione di cpdf_open() hanno l'identificatore del documento come loro primo parametro.

Attualmente questo identificatore non è usato internamente dato che ClibPDF non supporta la creazione di svariati documenti PDF contemporaneamente. Attualmente non bisognerebbe provare a farlo, dato che i risultati sono imprevedibili. Non è possibile controllare quali siano le conseguenze in un ambiente multi processo. Secondo l'autore di ClibPDF questo cambierà in una delle prossime release (la versione corrente quando questo è stato scritto è la 1.10). Se si ha bisogno di questa funzionalità utilizzare il modulo pdflib.

Un'interessante caratteristica di ClibPDF (e PDFlib) è l'abilità di creare il documento PDF completamente in memoria senza utilizzare file temporanei. Inoltre fornisce l'abilità di passare le coordinare in un'unità di lunghezza predefinita. (Questa caratteristica puo'essere simulata da pdf_translate() quando si utilizzano le funzioni PDFlib.)

Un'altra interessante caratteristica di ClibPDF è il fatto che ogni pagina può essere modificata in qualsiasi momento anche se è già stata aperta una nuova pagina. La funzione cpdf_set_current_page() permette di lasciare la pagina corrente e modificare un'altra pagina.

La maggioranza delle funzioni sono abbastanza facili da usare. La parte più difficile è probabilmente creare un simplice documento PDF. L'esempio seguente dovrebbe essere utile per cominciare. Crea un documento con una pagina. La pagina contiene il testo "Times-Roman" con un font di 30pt. Il testo è sottolineato.

Nota: Se si è interessati ad alternativi generatori PDF free non utilizzare le librerie PDF esterne, vedere questa FAQ per dettagli.

Requisiti

Per potere utilizzare le funzioni ClibPDF occorre installare il modulo ClibPDF. Questo è disponibile in FastIO, ma richiede l'acquisto di una licenza per uso commerciale. Il PHP richiede la libreria cpdflib >= 2.

Installazione

Per avere disponibili queste funzionalità occorre compilare il PHP con --with-cpdflib[=DIR]. Dove DIR indica la directory in cui è installato cpdflib, per default /usr. In aggiunta si può specificare le librerie jpeg e tiff da utilizzare. Per fare ciò aggiungere alla linea di configurazione le opzioni --with-jpeg-dir[=DIR] e --with-tiff-dir[=DIR].

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

CPDF_PM_NONE (integer)
CPDF_PM_OUTLINES (integer)
CPDF_PM_THUMBS (integer)
CPDF_PM_FULLSCREEN (integer)
CPDF_PL_SINGLE (integer)
CPDF_PL_1COLUMN (integer)
CPDF_PL_2LCOLUMN (integer)
CPDF_PL_2RCOLUMN (integer)

Esempi

Esempio 1. Semplice esempio ClibPDF

<?php
$cpdf = cpdf_open(0);
cpdf_page_init($cpdf, 1, 0, 595, 842, 1.0);
cpdf_add_outline($cpdf, 0, 0, 0, 1, "Page 1");
cpdf_begin_text($cpdf);
cpdf_set_font($cpdf, "Times-Roman", 30, "WinAnsiEncoding");
cpdf_set_text_rendering($cpdf, 1);
cpdf_text($cpdf, "Times Roman outlined", 50, 50);
cpdf_end_text($cpdf);
cpdf_moveto($cpdf, 50, 50);
cpdf_lineto($cpdf, 740, 330);
cpdf_stroke($cpdf);
cpdf_finalize_page($cpdf, 1);
cpdf_finalize($cpdf);
Header("Content-type: application/pdf");
cpdf_output_buffer($cpdf);
cpdf_close($cpdf);
?>

La distribuzione pdflib contiene un esempio più complicato che crea una serie di pagine con un orologio analogico. Di seguito si trova questo esempio convertito in PHP utilizzando l'estensione ClibPDF:

Esempio 2. esempio pdfclock dalla distribuzione pdflib 2.0

<?php
$radius = 200;
$margin = 20;
$pagecount = 40;

$pdf = cpdf_open(0);
cpdf_set_creator($pdf, "pdf_clock.php");
cpdf_set_title($pdf, "Analog Clock");

while ($pagecount-- > 0) {
  cpdf_page_init($pdf, $pagecount+1, 0, 2 * ($radius + $margin), 2 * ($radius + $margin), 1.0);

  cpdf_set_page_animation($pdf, 4, 0.5, 0, 0, 0);  /* wipe */

  cpdf_translate($pdf, $radius + $margin, $radius + $margin);
  cpdf_save($pdf);
  cpdf_setrgbcolor($pdf, 0.0, 0.0, 1.0);

  /* linee dei minuti */
  cpdf_setlinewidth($pdf, 2.0);
  for ($alpha = 0; $alpha < 360; $alpha += 6) {
    cpdf_rotate($pdf, 6.0);
    cpdf_moveto($pdf, $radius, 0.0);
    cpdf_lineto($pdf, $radius-$margin/3, 0.0);
    cpdf_stroke($pdf);
  }

  cpdf_restore($pdf);
  cpdf_save($pdf);

  /* linee dei 5 minuti */
  cpdf_setlinewidth($pdf, 3.0);
  for ($alpha = 0; $alpha < 360; $alpha += 30) {
    cpdf_rotate($pdf, 30.0);
    cpdf_moveto($pdf, $radius, 0.0);
    cpdf_lineto($pdf, $radius-$margin, 0.0);
    cpdf_stroke($pdf);
  }

  $ltime = getdate();

  /* disegna la lancetta delle ore */
  cpdf_save($pdf);
  cpdf_rotate($pdf, -(($ltime['minutes']/60.0) + $ltime['hours'] - 3.0) * 30.0);
  cpdf_moveto($pdf, -$radius/10, -$radius/20);
  cpdf_lineto($pdf, $radius/2, 0.0);
  cpdf_lineto($pdf, -$radius/10, $radius/20);
  cpdf_closepath($pdf);
  cpdf_fill($pdf);
  cpdf_restore($pdf);

  /* disegna la lancetta dei minuti */
  cpdf_save($pdf);
  cpdf_rotate($pdf, -(($ltime['seconds']/60.0) + $ltime['minutes'] - 15.0) * 6.0);
  cpdf_moveto($pdf, -$radius/10, -$radius/20);
  cpdf_lineto($pdf, $radius * 0.8, 0.0);
  cpdf_lineto($pdf, -$radius/10, $radius/20);
  cpdf_closepath($pdf);
  cpdf_fill($pdf);
  cpdf_restore($pdf);

  /* disegna la lancetta dei secondi */
  cpdf_setrgbcolor($pdf, 1.0, 0.0, 0.0);
  cpdf_setlinewidth($pdf, 2);
  cpdf_save($pdf);
  cpdf_rotate($pdf, -(($ltime['seconds'] - 15.0) * 6.0));
  cpdf_moveto($pdf, -$radius/5, 0.0);
  cpdf_lineto($pdf, $radius, 0.0);
  cpdf_stroke($pdf);
  cpdf_restore($pdf);

  /* disegna un piccolo cerchio al centro */
  cpdf_circle($pdf, 0, 0, $radius/30);
  cpdf_fill($pdf);

  cpdf_restore($pdf);

  cpdf_finalize_page($pdf, $pagecount+1);
}

cpdf_finalize($pdf);
Header("Content-type: application/pdf");
cpdf_output_buffer($pdf);
cpdf_close($pdf);
?>

Vedere anche:

Vedere anche la documentazione del modulo PDFlib.

Sommario
cpdf_add_annotation -- Aggiunge un'annotazione
cpdf_add_outline -- Aggiunge un segnalibro per la pagina corrente
cpdf_arc -- Disegna un arco
cpdf_begin_text -- Avvia una sezione di testo
cpdf_circle -- Disegna un cerchio
cpdf_clip -- Taglia dal path corrente
cpdf_close -- Chiude il documento PDF
cpdf_closepath_fill_stroke -- Close, fill and stroke current path
cpdf_closepath_stroke -- Chiude il path e disegna una linea lungo il path
cpdf_closepath -- Chiude la path corrente
cpdf_continue_text -- Scrive del testo nella riga seguente
cpdf_curveto -- Disegna una curva
cpdf_end_text -- Termina la sezione di testo
cpdf_fill_stroke -- Fill and stroke current path
cpdf_fill -- Riempie il path corrente
cpdf_finalize_page -- Chiude la pagina
cpdf_finalize -- Chiude il documento
cpdf_global_set_document_limits -- Sets document limits for any pdf document
cpdf_import_jpeg -- Apre un'immagine JPEG
cpdf_lineto -- Disegna una linea
cpdf_moveto -- Setta il punto corrente
cpdf_newpath -- Inizia un nuovo path
cpdf_open -- Apre un nuovo documento pdf
cpdf_output_buffer -- Scrive il documento pdf nel buffer di memoria
cpdf_page_init -- Inizia una nuova pagina
cpdf_place_inline_image -- Inserisce un'immagine nella pagina
cpdf_rect -- Disegna un rettangolo
cpdf_restore -- Ristabilisce le impostazioni salvate in precedenza
cpdf_rlineto -- Disegna una linea
cpdf_rmoveto -- Setta il punto corrente
cpdf_rotate_text -- Setta l'angolo di rotazione del testo
cpdf_rotate -- Effettua una rotazione
cpdf_save_to_file -- Salva il documento pdf in un file
cpdf_save -- Salva le impostazioni correnti
cpdf_scale -- Applica il coefficiente di scala
cpdf_set_action_url -- Imposta un link
cpdf_set_char_spacing -- Imposta la spaziatura fra caratteri
cpdf_set_creator -- Imposta il campo creatore nel documento pdf
cpdf_set_current_page -- Imposta la pagina corrente
cpdf_set_font_directories -- Imposta le directory in cui cercare quando si utilizzano font esterni
cpdf_set_font_map_file -- Imposta la tabella di associazione tra nome di file e nome di font, quando si usano font esterni
cpdf_set_font -- Seleziona l'aspetto e la dimensione del font corrente
cpdf_set_horiz_scaling -- Imposta il fattore di scala orizzontale del testo
cpdf_set_keywords -- Imposta i campi chiave del documento pdf
cpdf_set_leading -- Imposta la distanza fra righe di testo
cpdf_set_page_animation -- Sets duration between pages
cpdf_set_subject -- Imposta il campo soggetto del documento pdf
cpdf_set_text_matrix -- Imposta la matrice di testo
cpdf_set_text_pos -- Imposta la posizione del testo
cpdf_set_text_rendering -- Determines how text is rendered
cpdf_set_text_rise -- Sets the text rise
cpdf_set_title -- Imposta il campo titolo del documento pdf
cpdf_set_viewer_preferences -- How to show the document in the viewer
cpdf_set_word_spacing -- Imposta la spaziatura fra parole
cpdf_setdash -- Sets dash pattern
cpdf_setflat -- Sets flatness
cpdf_setgray_fill -- Imposta il grigio come colore per il riempimento
cpdf_setgray_stroke -- Sets drawing color to gray value
cpdf_setgray -- Imposta il grigio come colore per il disegno e il riempimento
cpdf_setlinecap -- Sets linecap parameter
cpdf_setlinejoin -- Sets linejoin parameter
cpdf_setlinewidth -- Imposta la larghezza delle linee
cpdf_setmiterlimit -- Sets miter limit
cpdf_setrgbcolor_fill -- Sets filling color to rgb color value
cpdf_setrgbcolor_stroke -- Sets drawing color to rgb color value
cpdf_setrgbcolor -- Imposta il valore del colore rgb come colore per il disegno e il riempimento
cpdf_show_xy -- Output text at position
cpdf_show -- Scrive il testo alla posizione corrente
cpdf_stringwidth -- Restituisce la larghezza del testo nel font corrente
cpdf_stroke -- Disegna una linea lungo il path
cpdf_text -- Scrive il testo con i parametri
cpdf_translate -- Sets origin of coordinate system

bool cpdf_end_text ( int documento_pdf )

La funzione cpdf_end_text() termina una sezione di testo cominciata con cpdf_begin_text(). Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempio 1. Output di testo
<?php cpdf_begin_text($pdf); cpdf_set_font($pdf, 16, "Helvetica", "WinAnsiEncoding"); cpdf_text($pdf, 100, 100, "Un pò di testo"); cpdf_end_text($pdf) ?>

Vedere anche cpdf_begin_text().

cpdf_fill_stroke

(PHP 3 >= 3.0.8, PHP 4, PHP 5 <= 5.0.4)

cpdf_fill_stroke -- Fill and stroke current path

Description

bool cpdf_fill_stroke ( int pdf_document )

The cpdf_fill_stroke() function fills the interior of the current path with the current fill color and draws current path. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

cpdf_fill

(PHP 3 >= 3.0.8, PHP 4, PHP 5 <= 5.0.4)

cpdf_fill -- Riempie il path corrente

Descrizione

bool cpdf_fill ( int documento_pdf )

La funzione cpdf_fill() riempie l'interno del path corrente con il colore di riempimento corrente. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche cpdf_closepath(), cpdf_stroke(), cpdf_setgray_fill(), cpdf_setgray(), cpdf_setrgbcolor_fill() e cpdf_setrgbcolor().

cpdf_finalize_page

(PHP 3 >= 3.0.10, PHP 4, PHP 5 <= 5.0.4)

cpdf_finalize_page -- Chiude la pagina

Descrizione

bool cpdf_finalize_page ( int documento_pdf, int numero_pagina )

La funzione cpdf_finalize_page() chiude la pagina numero numero della pagina. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Questa funzione serve solo a preservare la memoria. Una pagina chiusa occupa meno memoria ma non può più essere modificata.

Vedere anche cpdf_page_init().

cpdf_finalize

(PHP 3 >= 3.0.8, PHP 4, PHP 5 <= 5.0.4)

cpdf_finalize -- Chiude il documento

Descrizione

bool cpdf_finalize ( int documento_pdf )

La funzione cpdf_finalize() chiude il documento. Bisogna comunque richiamare cpdf_close(). Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche cpdf_close().

cpdf_global_set_document_limits

(PHP 4, PHP 5 <= 5.0.4)

cpdf_global_set_document_limits -- Sets document limits for any pdf document

int cpdf_open ( int compressione [, string nome_file] )

La funzione cpdf_open() apre un nuovo documento pdf. Il primo parametro setta il fattore di compressione del documento se è diverso da 0. Il secondo parametro, opzionale, setta il file in cui il documento viene scritto. Se è omesso il documento è creato in memoria e può essere scritto su un file con cpdf_save_to_file() oppure scritto sullo standard output con cpdf_output_buffer().

Nota: Il valore di ritorno sarà necessario nelle future versione di ClibPDF come primo parametro di tutte le altre funzioni che scrivono sul documento PDF.
La libreria ClibPDF considera il nome del file "-" come sinonimo di stdout. Se il PHP è compilato come modulo di apache questo però non funziona perchè il modo in cui ClibPDF scrive sullo stdout non funziona con apache. Si può risolvere questo problema saltando il nome del file e utilizzando cpdf_output_buffer() per scrivere il documento pdf.

Vedere anche cpdf_close() e cpdf_output_buffer().

cpdf_output_buffer

(PHP 3 >= 3.0.9, PHP 4, PHP 5 <= 5.0.4)

cpdf_output_buffer -- Scrive il documento pdf nel buffer di memoria

Description

bool cpdf_output_buffer ( int documento_pdf )

La funzione cpdf_output_buffer() scrive il documento pdf nello stdout. Il documento deve essere creato in memoria, cosa che si verifica se cpdf_open() è richiamata senza il nome di un file come parametro. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche cpdf_open().

cpdf_page_init

(PHP 3 >= 3.0.8, PHP 4, PHP 5 <= 5.0.4)

cpdf_page_init -- Inizia una nuova pagina

Descrizione

bool cpdf_page_init ( int documento_pdf, int numero_pagina, int orientamento, float altezza, float larghezza [, float unità] )

La funzione cpdf_page_init() inizia una nuova pagina con altezza height e larghezza width. Restituisce TRUE in caso di successo, FALSE in caso di fallimento. La pagina ha numero numero di pagina e orientamento orientamento. orientamento può essere 0 per l'orientamento verticale e 1 per l'orizzontale. L'ultimo parametro facoltativo unità setta le unità per il sistema di coordinate. Il valore deve essere il numero di punti postscript per unità. Dato che un pollice corrisponde a 72 punti, un valore di 72 setterà l'unità ad un pollice. Il valore di default è sempre 72.

Vedere cpdf_set_current_page().

cpdf_place_inline_image

(PHP 3 >= 3.0.9, PHP 4, PHP 5 <= 5.0.4)

cpdf_place_inline_image -- Inserisce un'immagine nella pagina

Descrizione

bool cpdf_place_inline_image ( int documento_pdf, int immagine, float x-coor, float y-coor, float angolo, float larghezza, float altezza [, int modo] )

La funzione cpdf_place_inline_image() inserisce un'immagine creata con le funzioni per le immagini di PHP nella pagina alla posizione (x-coor, y-coor). L'immagine può essere ridimensionata nello stesso tempo. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche cpdf_import_jpeg().

cpdf_rect

(PHP 3 >= 3.0.8, PHP 4, PHP 5 <= 5.0.4)

cpdf_rect -- Disegna un rettangolo

Descrizione

bool cpdf_rect ( int documento_pdf, float x-coor, float y-coor, float larghezza, float altezza [, int modo] )

La funzione cpdf_rect() disegna un rettangolo con l'angolo in basso a sinistra nel punto (x-coor, y-coor). La larghezza è settata a larghezza. L'altezza è settata a altezza. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempio 1. Traccia un rettangolo
<?php $cpdf = cpdf_open(0); cpdf_page_init($cpdf, 1, 0, 595, 842, 1.0); // imposta il colore di riempimento a rosso cpdf_setrgbcolor($cpdf, 1, 0, 0); // traccia il rettangolo di (180 * 100) cpdf_rect($cpdf, 645, 400, 180, 100); // riempie il rettangolo cpdf_fill($cpdf); cpdf_finalize($cpdf); Header("Content-type: application/pdf"); cpdf_output_buffer($cpdf); cpdf_close($cpdf); ?>

cpdf_restore

(PHP 3 >= 3.0.8, PHP 4, PHP 5 <= 5.0.4)

cpdf_restore -- Ristabilisce le impostazioni salvate in precedenza

Descrizione

bool cpdf_restore ( int documento_pdf )

La funzione cpdf_restore() ristabilisce le impostazioni salvate con cpdf_save(). Funziona come il comando postscript grestore. Molto utile se si vuole traslare o ruotare un oggetto senza intaccare gli altri oggetti. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

La funzione cpdf_rotate() effettua una rotazione di angolo gradi. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

cpdf_save_to_file

(PHP 3 >= 3.0.8, PHP 4, PHP 5 <= 5.0.4)

cpdf_save_to_file -- Salva il documento pdf in un file

Descrizione

bool cpdf_save_to_file ( int documento_pdf, string nome_file )

La funzione cpdf_save_to_file() salva il documento pdf in un file se è stato creato in memoria. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Questa funzione non è necessaria se il documento pdf è stato aperto specificando un nome di un file come parametro di cpdf_open().

Vedere anche: cpdf_output_buffer() e cpdf_open().

cpdf_save

(PHP 3 >= 3.0.8, PHP 4, PHP 5 <= 5.0.4)

cpdf_save -- Salva le impostazioni correnti

Descrizione

bool cpdf_save ( int documento_pdf )

La funzione cpdf_save() salva le impostazioni correnti. Funziona come il comando postscript gsave. Molto utile se si vuole traslare o ruotare un oggetto senza intaccare gli altri oggetti. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche cpdf_restore().

cpdf_scale

(PHP 3 >= 3.0.8, PHP 4, PHP 5 <= 5.0.4)

cpdf_scale -- Applica il coefficiente di scala

bool cpdf_set_font ( int documento_pdf, string nome_font, float dimensione, string codifica )

La funzione cpdf_set_font() imposta l'aspetto, la dimensione e la codifica del font corrente. Attualmente solo i font standard postscript sono supportati. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

L'ultimo parametro codifica può assumere i seguenti valori: "MacRomanEncoding", "MacExpertEncoding", "WinAnsiEncoding", e "NULL". "NULL" rappresenta la codifica incorporata del font.

Vedere il manuale di ClibPDF per maggiori informazioni, specialmente su come supportare font asiatici.

cpdf_set_horiz_scaling

(PHP 3 >= 3.0.8, PHP 4, PHP 5 <= 5.0.4)

cpdf_set_horiz_scaling -- Imposta il fattore di scala orizzontale del testo

bool cpdf_set_page_animation ( int pdf_document, int transition, float duration )

The cpdf_set_page_animation() function set the transition between following pages. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

The value of transition can be

0 for none,

1 for two lines sweeping across the screen reveal the page,

2 for multiple lines sweeping across the screen reveal the page,

3 for a box reveals the page,

4 for a single line sweeping across the screen reveals the page,

5 for the old page dissolves to reveal the page,

6 for the dissolve effect moves from one screen edge to another,

7 for the old page is simply replaced by the new page (default)

The value of duration is the number of seconds between page flipping.

cpdf_set_subject

(PHP 3 >= 3.0.8, PHP 4, PHP 5 <= 5.0.4)

cpdf_set_subject -- Imposta il campo soggetto del documento pdf

Descrizione

bool cpdf_set_subject ( int pdf_document, string soggetto )

La funzione cpdf_set_subject() imposta il soggetto del documento pdf. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche cpdf_set_title(), cpdf_set_creator() e cpdf_set_keywords().

cpdf_set_text_matrix

(PHP 3 >= 3.0.8, PHP 4, PHP 5 <= 5.0.4)

cpdf_set_text_matrix -- Imposta la matrice di testo

Descrizione

bool cpdf_set_text_matrix ( int documento_pdf, array matrice )

La funzione cpdf_set_text_matrix() imposta una matrmatriceice che descrive una trasformazione applicata sul font corrente. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

cpdf_set_text_pos

(PHP 3 >= 3.0.8, PHP 4, PHP 5 <= 5.0.4)

cpdf_set_text_pos -- Imposta la posizione del testo

Descrizione

bool cpdf_set_text_pos ( int documento_pdf, float x-coor, float y-coor [, int modo] )

La funzione cpdf_set_text_pos() imposta la posizione del testo per la prossima chiamata della funzione cpdf_show(). Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche: cpdf_show() e cpdf_text().

cpdf_set_text_rendering

(PHP 3 >= 3.0.8, PHP 4, PHP 5 <= 5.0.4)

cpdf_set_text_rendering -- Determines how text is rendered

Description

bool cpdf_set_text_rendering ( int pdf_document, int rendermode )

The cpdf_set_text_rendering() function determines how text is rendered. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

The possible values for rendermode are 0=fill text, 1=stroke text, 2=fill and stroke text, 3=invisible, 4=fill text and add it to clipping path, 5=stroke text and add it to clipping path, 6=fill and stroke text and add it to clipping path, 7=add it to clipping path.

cpdf_set_text_rise

(PHP 3 >= 3.0.8, PHP 4, PHP 5 <= 5.0.4)

cpdf_set_text_rise -- Sets the text rise

Description

bool cpdf_set_text_rise ( int pdf_document, float value )

The cpdf_set_text_rise() function sets the text rising to value units. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

cpdf_set_title

(PHP 3 >= 3.0.8, PHP 4, PHP 5 <= 5.0.4)

cpdf_set_title -- Imposta il campo titolo del documento pdf

Descrizione

bool cpdf_set_title ( int pdf_document, string titolo )

La funzione cpdf_set_title() imposta il titolo di un documento pdf. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche: cpdf_set_subject(), cpdf_set_creator() e cpdf_set_keywords().

cpdf_set_viewer_preferences

(PHP 3 >= 3.0.9, PHP 4, PHP 5 <= 5.0.4)

cpdf_set_viewer_preferences -- How to show the document in the viewer

Description

bool cpdf_set_viewer_preferences ( int pdfdoc, array preferences )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

cpdf_set_word_spacing

(PHP 3 >= 3.0.8, PHP 4, PHP 5 <= 5.0.4)

cpdf_set_word_spacing -- Imposta la spaziatura fra parole

Descrizione

bool cpdf_set_word_spacing ( int documento_pdf, float spaziatura )

La funzione cpdf_set_word_spacing() imposta la spaziatura fra parole. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche: cpdf_set_char_spacing() e cpdf_set_leading().

cpdf_setdash

(PHP 3 >= 3.0.8, PHP 4, PHP 5 <= 5.0.4)

cpdf_setdash -- Sets dash pattern

bool cpdf_setrgbcolor_fill ( int pdf_document, float red_value, float green_value, float blue_value )

The cpdf_setrgbcolor_fill() function sets the current rgb color value to fill a path.

Nota: The values are expected to be floating point values between 0.0 and 1.0. (i.e black is (0.0, 0.0, 0.0) and white is (1.0, 1.0, 1.0)).

cpdf_setrgbcolor_stroke

(PHP 3 >= 3.0.8, PHP 4, PHP 5 <= 5.0.4)

cpdf_setrgbcolor_stroke -- Sets drawing color to rgb color value

Description

bool cpdf_setrgbcolor_stroke ( int pdf_document, float red_value, float green_value, float blue_value )

The cpdf_setrgbcolor_stroke() function sets the current drawing color to the given rgb color value. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Nota: The values are expected to be floating point values between 0.0 and 1.0. (i.e black is (0.0, 0.0, 0.0) and white is (1.0, 1.0, 1.0)).

cpdf_setrgbcolor

(PHP 3 >= 3.0.8, PHP 4, PHP 5 <= 5.0.4)

cpdf_setrgbcolor -- Imposta il valore del colore rgb come colore per il disegno e il riempimento

Descrizione

bool cpdf_setrgbcolor ( int documento_pdf, float valore_rosso, float valore_verde, float valore_blu )

La funzione cpdf_setrgbcolor() imposta il colore corrente per il disegno e il riempimento al valore del colore rgb dato. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Nota: The values are expected to be floating point values between 0.0 and 1.0. (i.e black is (0.0, 0.0, 0.0) and white is (1.0, 1.0, 1.0)).

Vedere anche: cpdf_setrgbcolor_stroke() e cpdf_setrgbcolor_fill().

cpdf_show_xy

(PHP 3 >= 3.0.8, PHP 4, PHP 5 <= 5.0.4)

cpdf_show_xy -- Output text at position

Description

bool cpdf_show_xy ( int pdf_document, string text, float x-coor, float y-coor [, int mode] )

The cpdf_show_xy() function outputs the string text at position with coordinates (x-coor, y-coor). Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Nota: The function cpdf_show_xy() is identical to cpdf_text() without the optional parameters.

cpdf_show

(PHP 3 >= 3.0.8, PHP 4, PHP 5 <= 5.0.4)

cpdf_show -- Scrive il testo alla posizione corrente

Descrizione

bool cpdf_show ( int documento_pdf, string testo )

La funzione cpdf_show() scrive la stringa in testo alla posizione corrente. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche: cpdf_text(), cpdf_begin_text() e cpdf_end_text().

cpdf_stringwidth

(PHP 3 >= 3.0.8, PHP 4, PHP 5 <= 5.0.4)

cpdf_stringwidth -- Restituisce la larghezza del testo nel font corrente

Descrizione

float cpdf_stringwidth ( int documento_pdf, string testo )

La funzione cpdf_stringwidth() restituisce la larghezza della stringa in testo. Richiede che un font sia settato in precedenza.

Vedere anche cpdf_set_font().

cpdf_stroke

(PHP 3 >= 3.0.8, PHP 4, PHP 5 <= 5.0.4)

cpdf_stroke -- Disegna una linea lungo il path

Description

bool cpdf_stroke ( int documento_pdf )

La funzione cpdf_stroke() disegna una linea lungo il path corrente. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche: cpdf_closepath() e cpdf_closepath_stroke().

cpdf_text

(PHP 3 >= 3.0.8, PHP 4, PHP 5 <= 5.0.4)

cpdf_text -- Scrive il testo con i parametri

Descrizione

bool cpdf_text ( int documento_pdf, string testo, float x-coor, float y-coor [, int modo [, float orientamento [, int allineamento]]] )

La funzione cpdf_text() scrive la stringa testo alla posizione con coordinate (x-coor, y-coor). Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Il parametro facoltativo orientamento è la rotazione del testo in gradi.

Il parametro facoltativo allineamento determina come viene allineato il testo.

Vedere la documentazione ClibPDF per i possibili valori.

Vedere anche cpdf_show_xy().

cpdf_translate

(PHP 3 >= 3.0.8, PHP 4, PHP 5 <= 5.0.4)

cpdf_translate -- Sets origin of coordinate system

Description

bool cpdf_translate ( int pdf_document, float x-coor, float y-coor [, int mode] )

The cpdf_translate() function set the origin of coordinate system to the point (x-coor, y-coor). Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

XV. Funzioni di supporto COM per Windows

Introduzione

COM è una tecnologia che permette il riutilizzo del codice scritto in un qualsiasi linguaggio utilizzando una convenzione standard di chiamate e nascondendo dietro a delle API i dettagli di implementazione quali la macchina su cui il Componente è conservato e il file eseguibile che lo ospita. Si può pernsare a COM com a un meccanismo avanzato di Remote Procedure Call (RPC) con alcune basi di programmazione ad oggetti. COM separa l'implementazione dall'interfaccia.

COM incoraggia il versioning, la separazione tra interfaccia e implementazione e l'occultamento dei dettagli dell'implementazione, come la posizione dell'eseguibile e il linguaggio di programmazione.

Requisiti

Le funzioni COM sono disponibili solo sulle versioni Windows di PHP.

Installazione

Non è necessaria nessuna installazione per usare queste funzioni, esse fanno parte del core di PHP.

La versione per Windows di PHP ha già compilato il supporto per questo modulo. Non occorre caricare alcun modulo addizionale per potere utilizzare queste funzioni.

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

Tabella 1. opzioni di configurazione Com

Nome	Default	Modificabile in	Log variazioni
com.allow_dcom	"0"	PHP_INI_SYSTEM	Disponibile dal PHP 4.0.5.
com.autoregister_typelib	"0"	PHP_INI_SYSTEM	PHP_INI_SYSTEM in PHP 4. Disponibile in PHP 4.1.0.
com.autoregister_verbose	"0"	PHP_INI_SYSTEM	PHP_INI_SYSTEM in PHP 4. Disponibile dal PHP 4.1.0.
com.autoregister_casesensitive	"1"	PHP_INI_SYSTEM	PHP_INI_SYSTEM in PHP 4. Disponibile dal PHP 4.1.0.
com.code_page	""	PHP_INI_ALL	Disponibile dal PHP 5.0.0.
com.typelib_file	""	PHP_INI_SYSTEM	Disponibile dal PHP 4.0.5.

Per maggiori dettagli sulle costanti PHP_INI_* vedere Appendice G.

Breve descrizione dei parametri di configurazione.

com.allow_dcom

Quando è impostato a on, il PHP è abilitao ad operare come client D-COM (COM distribuito) e permette agli script PHP di istanziare oggetti COM su un server remoto.

com.autoregister_typelib

Quando questo parametro è impostato a on il PHP tenta di registrare costanti dalla libreria dei tipi dell'oggetto che istanzia, se l'pggetto implementa l'interfaccia richiesta per ottenere le informazioni in oggetto. Se distinguere tra nomi dlle costanti maiuscoli e minuscoli è controllato dal parametro com.autoregister_casesensitive .

com.autoregister_verbose

When this is turned on, any problems with loading a typelibrary during object instantiation will be reported using the PHP error mechanism. The default is off, which does not emit any indication if there was an error finding or loading the type library.

com.autoregister_casesensitive

When this is turned on (the default), constants found in auto-loaded type libraries will be registered case sensitively. See com_load_typelib() for more details.

com.code_page

It controls the default character set code-page to use when passing strings to and from COM objects. If set to an empty string, PHP will assume that you want CP_ACP, which is the default system ANSI code page.

If the text in your scripts is encoded using a different encoding/character set by default, setting this directive will save you from having to pass the code page as a parameter to the COM class constructor. Please note that by using this directive (as with any PHP configuration directive), your PHP script becomes less portable; you should use the COM constructor parameter whenever possible.

Nota: This configuration directive was introduced with PHP 5.

com.typelib_file

When set, this should hold the path to a file that contains a list of typelibraries that should be loaded on startup. Each line of the file will be treated as the type library name and loaded as though you had called com_load_typelib(). The constants will be registered persistently, so that the library only needs to be loaded once. If a type library name ends with the string #cis or #case_insensitive, then the constants from that library will be registered case insensitively.

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

CLSCTX_INPROC_SERVER (integer)
CLSCTX_INPROC_HANDLER (integer)
CLSCTX_LOCAL_SERVER (integer)
CLSCTX_REMOTE_SERVER (integer)
CLSCTX_SERVER (integer)
CLSCTX_ALL (integer)
VT_NULL (integer)
VT_EMPTY (integer)
VT_UI1 (integer)
VT_I2 (integer)
VT_I4 (integer)
VT_R4 (integer)
VT_R8 (integer)
VT_BOOL (integer)
VT_ERROR (integer)
VT_CY (integer)
VT_DATE (integer)
VT_BSTR (integer)
VT_DECIMAL (integer)
VT_UNKNOWN (integer)
VT_DISPATCH (integer)
VT_VARIANT (integer)
VT_I1 (integer)
VT_UI2 (integer)
VT_UI4 (integer)
VT_INT (integer)
VT_UINT (integer)
VT_ARRAY (integer)
VT_BYREF (integer)
CP_ACP (integer)
CP_MACCP (integer)
CP_OEMCP (integer)
CP_UTF7 (integer)
CP_UTF8 (integer)
CP_SYMBOL (integer)
CP_THREAD_ACP (integer)

Vedere anche:

Per maggiori informazioni su COM si leggano le specifiche COM o si guardi anche la documentazione di Don Box su Yet Another COM Library (YACL)

Sommario
COM -- classe COM
DOTNET -- DOTNET class
VARIANT -- classe VARIANT
com_addref -- Incrementa il contatore di referenze.
com_create_guid -- Generate a globally unique identifier (GUID)
com_event_sink -- Connect events from a COM object to a PHP object
com_get_active_object -- Returns a handle to an already running instance of a COM object
com_get -- Ricava il valore di una proprietà di un componente COM
com_invoke -- Chiama un metodo di un componente COM.
com_isenum -- Recupera un IEnumVariant
com_load_typelib -- Carica una Typelib
com_load -- Crea un nuovo riferimento a un componente COM
com_message_pump -- Process COM messages, sleeping for up to timeoutms milliseconds
com_print_typeinfo -- Print out a PHP class definition for a dispatchable interface
com_propget -- Alias di com_get()
com_propput -- Alias di com_set()
com_propset -- Alias di com_set()
com_release -- Decrementa il contaotre di referenze.
com_set -- Assegna un valore a una proprietà di un oggetto COM
variant_abs -- Returns the absolute value of a variant
variant_add -- "Adds" two variant values together and returns the result
variant_and -- performs a bitwise AND operation between two variants and returns the result
variant_cast -- Convert a variant into a new variant object of another type
variant_cat -- concatenates two variant values together and returns the result
variant_cmp -- Compares two variants
variant_date_from_timestamp -- Returns a variant date representation of a unix timestamp
variant_date_to_timestamp -- Converts a variant date/time value to unix timestamp
variant_div -- Returns the result from dividing two variants
variant_eqv -- Performs a bitwise equivalence on two variants
variant_fix -- Returns the integer portion ? of a variant
variant_get_type -- Returns the type of a variant object
variant_idiv -- Converts variants to integers and then returns the result from dividing them
variant_imp -- Performs a bitwise implication on two variants
variant_int -- Returns the integer portion of a variant
variant_mod -- Divides two variants and returns only the remainder
variant_mul -- multiplies the values of the two variants and returns the result
variant_neg -- Performs logical negation on a variant
variant_not -- Performs bitwise not negation on a variant
variant_or -- Performs a logical disjunction on two variants
variant_pow -- Returns the result of performing the power function with two variants
variant_round -- Rounds a variant to the specified number of decimal places
variant_set_type -- Convert a variant into another type "in-place"
variant_set -- Assigns a new value for a variant object
variant_sub -- subtracts the value of the right variant from the left variant value and returns the result
variant_xor -- Performs a logical exclusion on two variants

COM

(no version information, might be only in CVS)

COM -- classe COM

Sinossi

$obj = new COM("server.object")

Descrizione

La classe COM fornisce un ambiente per integrare i componenti (D)COM negli script PHP.

Metodi

string COM::COM ( string nome_modulo [, string nome_server [, int codepage]] )

costruttore della classe COM. Parametri:

nome_modulo: nome o class-id del componente desiderato.
nome_server: nome del server DCOM dal quale deve essere richiamato il componente. Se NULL, si assume localhost. Per permettere l'uso di DCOM il parametro com.allow_dcom deve essere impostato a TRUE in php.ini.
codepage: specifica la codepage che verrà usata per convertire le stringhe di PHP in stringhe Unicode e viceversa. I valori possibili sono CP_ACP, CP_MACCP, CP_OEMCP, CP_SYMBOL, CP_THREAD_ACP, CP_UTF7 e CP_UTF8.

Esempio 1. esempio di COM (1)
<?php // esecuzione di Word $word = new COM("word.application") or die("Non sono riuscito ad eseguire Word"); echo "Word caricato, versione {$word->Version}\n"; //lo porta in primo piano $word->Visible = 1; //apre un documento vuoto $word->Documents->Add(); //esegue un po' di operazioni inutili $word->Selection->TypeText("Questa è una prova..."); $word->Documents[1]->SaveAs("Prova inutile.doc"); //chiude Word $word->Quit(); //libera l'oggetto $word->Release(); $word = null; ?>

Esempio 2. esempio di COM (2)
<?php $conn = new COM("ADODB.Connection") or die("non riesco ad attivare ADO"); $conn->Open("Provider=SQLOLEDB; Data Source=localhost; Initial Catalog=database; User ID=user; Password=password"); $rs = $conn->Execute("SELECT * FROM unatabella"); // Recordset $num_colonne = $rs->Fields->Count(); echo $num_columns . "\n"; for ($i=0; $i < $num_colonne; $i++) { $campi[$i] = $rs->Fields($i); } $contorighe = 0; while (!$rs->EOF) { for ($i=0; $i < $num_colonne; $i++) { echo $campi[$i]->value . "\t"; } echo "\n"; $contorighe++; // incrementa contorighe $rs->MoveNext(); } $rs->Close(); $conn->Close(); $rs->Release(); $conn->Release(); $rs = null; $conn = null; ?>

DOTNET

(no version information, might be only in CVS)

DOTNET -- DOTNET class

Sinossi

$obj = new DOTNET("assembly", "classname")

Description

The DOTNET class allows you to instantiate a class from a .Net assembly and call its methods and access its properties.

Methods

string DOTNET::DOTNET ( string assembly_name, string class_name [, int codepage] )

DOTNET class constructor. assembly_name specifies which assembly should be loaded, and class_name specifices which class in that assembly to instantiate. You may optionally specify a codepage to use for unicode string transformations; see the COM class for more details on code pages.

The returned object is an overloaded object, which means that PHP does not see any fixed methods as it does with regular classes; instead, any property or method accesses are passed through to COM and from there to DOTNET. In other words, the .Net object is mapped through the COM interoperability layer provided by the .Net runtime.

Once you have created a DOTNET object, PHP treats it identically to any other COM object; all the same rules apply.

Esempio 1. DOTNET example
<?php $stack = new DOTNET("mscorlib", "System.Collections.Stack"); $stack->Push(".Net"); $stack->Push("Hello "); echo $stack->Pop() . $stack->Pop(); ?>

Nota: You need to install the .Net runtime on your web server to take advantage of this feature.

VARIANT

(no version information, might be only in CVS)

VARIANT -- classe VARIANT

Sinossi

$vVar = new VARIANT($var)

Descrizione

Un semplice contenitore per includere le variabili in strutture VARIANT.

Metodi

string VARIANT::VARIANT ( [mixed valore [, int tipo [, int codepage]]] )

costruttore della classe VARIANT. Parametri:

valore: valore iniziale. se omesso viene creato un oggetto VT_EMPTY.
tipo: specifica il tipo di contenuto dell'oggetto VARIANT. I valori possibili sono VT_UI1, VT_UI2, VT_UI4, VT_I1, VT_I2, VT_I4, VT_R4, VT_R8, VT_INT, VT_UINT, VT_BOOL, VT_ERROR, VT_CY, VT_DATE, VT_BSTR, VT_DECIMAL, VT_UNKNOWN, VT_DISPATCH e VT_VARIANT. Questi valori sono mutuallmente esclusivi, ma possono essere combinati con VT_BYREF per specificare che è un valore. Se omesso, viene usato il tipo di valore. Consultare la libreria MSDN per ulteriori informazioni.
codepage: specifica la codepage che è usata per convertire le stringhe PHP in stringhe unicode e viceversa. I valori possibili sono CP_ACP, CP_MACCP, CP_OEMCP, CP_SYMBOL, CP_THREAD_ACP, CP_UTF7 e CP_UTF8.

com_addref

(PHP 4 >= 4.1.0)

com_addref -- Incrementa il contatore di referenze.

Descrizione

void com_addref ( void )

Incrementa il contatore di referenze.

com_create_guid

(PHP 5)

com_create_guid -- Generate a globally unique identifier (GUID)

Description

string com_create_guid ( void )

Generates a Globally Unique Identifier (GUID) and returns it as a string. A GUID is generated in the same way as DCE UUID's, except that the Microsoft convention is to enclose a GUID in curly braces.

See also uuid_create() in the PECL uuid extension.

com_event_sink

(PHP 4 >= 4.2.3, PHP 5)

com_event_sink -- Connect events from a COM object to a PHP object

Description

bool com_event_sink ( variant comobject, object sinkobject [, mixed sinkinterface] )

Instructs COM to sink events generated by comobject into the PHP object sinkobject. PHP will attempt to use the default dispinterface type specified by the typelibrary associated with comobject, but you may override this choice by setting sinkinterface to the name of the dispinterface that you want to use.

sinkobject should be an instance of a class with methods named after those of the desired dispinterface; you may use com_print_typeinfo() to help generate a template class for this purpose.

Be careful how you use this feature; if you are doing something similar to the example below, then it doesn't really make sense to run it in a web server context.

Esempio 1. COM event sink example

<?php
class IEEventSinker {
  var $terminated = false;

  function ProgressChange($progress, $progressmax) {
    echo "Download progress: $progress / $progressmax\n";
  }

  function DocumentComplete(&$dom, $url) {
    echo "Document $url complete\n";
  }

  function OnQuit() {
    echo "Quit!\n";
    $this->terminated = true;
  }
}
$ie = new COM("InternetExplorer.Application");
// note that you don't need the & for PHP 5!
$sink =& new IEEventSinker();
com_event_sink($ie, $sink, "DWebBrowserEvents2");
$ie->Visible = true;
$ie->Navigate("http://www.php.net");
while(!$sink->terminated) {
  com_message_pump(4000);
}
$ie = null;
?>

com_get_active_object

(PHP 5)

com_get_active_object -- Returns a handle to an already running instance of a COM object

Description

variant com_get_active_object ( string progid [, int code_page] )

com_get_active_object() is similar to creating a new instance of a COM object, except that it will only return an object to your script if the object is already running. OLE applications use something known as the Running Object Table to allow well-known applications to be launched only once; this function exposes the COM library function GetActiveObject() to get a handle on a running instance.

progid must be either the ProgID or CLSID for the object that you want to access (for example Word.Application). code_page acts in precisely the same way that it does for the COM class.

If the requested object is running, it will be returned to your script just like any other COM object. Otherwise a com_exception will be raised. There are a variety of reasons why this function might fail, the most common being that the object is not already running. In that situation, the exception error code will be MK_E_UNAVAILABLE; you can use the getCode method of the exception object to check the exception code.

void com_isenum ( object modulo_com )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

com_load_typelib

(PHP 4 >= 4.1.0, PHP 5)

com_load_typelib -- Carica una Typelib

Descrizione

void com_load_typelib ( string nome_typelib [, int ignora_maiuscole] )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

com_load

(PHP 4)

com_load -- Crea un nuovo riferimento a un componente COM

Descrizione

string com_load ( string nome_modulo [, string nome_server [, int codepage]] )

com_load() crea un nuovo componente COM e ne restituisce un riferimento. Restituisce FALSE in caso di errore. I possibili valori per codepage sono CP_ACP, CP_MACCP, CP_OEMCP, CP_SYMBOL, CP_THREAD_ACP, CP_UTF7 e CP_UTF8.

com_message_pump

(PHP 4 >= 4.2.3, PHP 5)

com_message_pump -- Process COM messages, sleeping for up to timeoutms milliseconds

Description

bool com_message_pump ( [int timeoutms] )

This function will sleep for up to timeoutms milliseconds, or until a message arrives in the queue. If a message or messages arrives before the timeout, they will be dispatched, and the function will return TRUE. If the timeout occurs and no messages were processed, the return value will be FALSE. If you do not specify a value for timeoutms, then 0 will be assumed. A 0 value means that no waiting will be performed; if there are messages pending they will be dispatched as before; if there are no messages pending, the function will return FALSE immediately without sleeping.

The purpose of this function is to route COM calls between apartments and handle various synchronization issues. This allows your script to wait efficiently for events to be triggered, while still handling other events or running other code in the background. You should use it in a loop, as demonstrated by the example in the com_event_sink() function, until you are finished using event bound COM objects.

com_print_typeinfo

(PHP 4 >= 4.2.3, PHP 5)

com_print_typeinfo -- Print out a PHP class definition for a dispatchable interface

Description

bool com_print_typeinfo ( object comobject [, string dispinterface [, bool wantsink]] )

The purpose of this function is to help generate a skeleton class for use as an event sink. You may also use it to generate a dump of any COM object, provided that it supports enough of the introspection interfaces, and that you know the name of the interface you want to display.

void com_release ( void )

Decrementa il contatore di referenze.

com_set

(PHP 3 >= 3.0.3, PHP 4)

com_set -- Assegna un valore a una proprietà di un oggetto COM

Descrizione

void com_set ( resource oggetto_com, string nome_prop, mixed valore )

Imposta il valore della proprietà nome_prop del componente COM referenziato da oggetto_com. Restituisce il valore appena impostato in caso di successo,, FALSE altrimenti.

variant_abs

(PHP 5)

variant_abs -- Returns the absolute value of a variant

Description

This function wraps VariantChangeType() in the COM library; consult MSDN for more information.

variant_cat

(PHP 5)

variant_cat -- concatenates two variant values together and returns the result

Description

mixed variant_cat ( mixed left, mixed right )

Concatenates left with right and returns the result.

See also la Sezione Operatori di stringa nel Capitolo 15 for the string concatenation operator; this function is notionally equivalent to $left . $right.

Nota: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.
The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.

variant_cmp

(PHP 5)

variant_cmp -- Compares two variants

Description

int variant_cmp ( mixed left, mixed right [, int lcid [, int flags]] )

Compares left with right and returns one of the following values:

Tabella 1. Variant Comparision Results

value	meaning
`VARCMP_LT`	`left` is less than `right`
`VARCMP_EQ`	`left` is equal to `right`
`VARCMP_GT`	`left` is greater than `right`
`VARCMP_NULL`	Either `left`, `right` or both are `NULL`

This function will only compare scalar values, not arrays or variant records.

lcid is a valid Locale Identifier to use when comparing strings (this affects string collation). flags can be one or more of the following values OR'd together, and affects string comparisons:

Tabella 2. Variant Comparision Flags

value	meaning
`NORM_IGNORECASE`	Compare case insensitively
`NORM_IGNORENONSPACE`	Ignore nonspacing characters
`NORM_IGNORESYMBOLS`	Ignore symbols
`NORM_IGNOREWIDTH`	Ignore string width
`NORM_IGNOREKANATYPE`	Ignore Kana type
`NORM_IGNOREKASHIDA`	Ignore Arabic kashida characters

Nota: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.
The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.

If	Then
Both expressions are of the string, date, character, boolean type	Double is returned
One expression is a string type and the other a character	Division and a double is returned
One expression is numeric and the other is a string	Division and a double is returned.
Both expressions are numeric	Division and a double is returned
Either expression is NULL	NULL is returned
`right` is empty and `left` is anything but empty	A com_exception with code `DISP_E_DIVBYZERO` is thrown
`left` is empty and `right` is anything but empty.	0 as type double is returned
Both expressions are empty	A com_exception with code `DISP_E_OVERFLOW` is thrown

Nota: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.
The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.

variant_eqv

(PHP 5)

variant_eqv -- Performs a bitwise equivalence on two variants

Description

mixed variant_eqv ( mixed left, mixed right )

If each bit in left is equal to the corresponding bit in right then TRUE is returned, otherwise FALSE is returned.

Nota: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.
The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.

variant_fix

(PHP 5)

variant_fix -- Returns the integer portion ? of a variant

Description

mixed variant_fix ( mixed variant )

If variant is negative, then the first negative integer greater than or equal to the variant is returned, otherwise returns the integer portion of the value of variant.

Avvertimento

This documentation is based on the MSDN documentation; it appears that this function is either the same as variant_int(), or that there is an error in the MSDN documentation.

Nota: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.
The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.

Nota: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.
The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.

variant_int

(PHP 5)

variant_int -- Returns the integer portion of a variant

Description

mixed variant_int ( mixed variant )

If variant is negative, then the first negative integer greater than or equal to the variant is returned, otherwise returns the integer portion of the value of variant.

Nota: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.
The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.

variant_mod

(PHP 5)

variant_mod -- Divides two variants and returns only the remainder

Description

mixed variant_mod ( mixed left, mixed right )

Divides left by right and returns the remainder.

Nota: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.
The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.

variant_mul

(PHP 5)

variant_mul -- multiplies the values of the two variants and returns the result

Description

mixed variant_mul ( mixed left, mixed right )

Multiplies left by right and returns the result, subject to the following rules:

Tabella 1. Variant Multiplication Rules

If	Then
Both expressions are of the string, date, character, boolean type	Multiplication
One expression is a string type and the other a character	Multiplication
One expression is numeric and the other is a string	Multiplication
Both expressions are numeric	Multiplication
Either expression is NULL	NULL is returned
Both expressions are empty	Empty string is returned

Boolean values are converted to -1 for FALSE and 0 for TRUE.

Nota: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.
The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.

variant_neg

(PHP 5)

variant_neg -- Performs logical negation on a variant

Description

mixed variant_neg ( mixed variant )

Performs logical negation of variant and returns the result.

Nota: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.
The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.

variant_not

(PHP 5)

variant_not -- Performs bitwise not negation on a variant

Description

mixed variant_not ( mixed variant )

Performs bitwise not negation on variant and returns the result. If variant is NULL, the result will also be NULL.

Nota: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.
The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.

variant_or

(PHP 5)

variant_or -- Performs a logical disjunction on two variants

Description

mixed variant_or ( mixed left, mixed right )

Performs a bitwise OR operation, according to the following truth table; note that this is slightly different from a regular OR operation.

Tabella 1. Variant OR Rules

If `left` is	If `right` is	then the result is
`TRUE`	`TRUE`	`TRUE`
`TRUE`	`FALSE`	`TRUE`
`TRUE`	`NULL`	`TRUE`
`FALSE`	`TRUE`	`TRUE`
`FALSE`	`FALSE`	`FALSE`
`FALSE`	`NULL`	`NULL`
`NULL`	`TRUE`	`TRUE`
`NULL`	`FALSE`	`NULL`
`NULL`	`NULL`	`NULL`

Nota: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.
The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.

Tabella 1. Variant Subtraction Rules

If	Then
Both expressions are of the string type	Subtraction
One expression is a string type and the other a character	Subtraction
One expression is numeric and the other is a string	Subtraction.
Both expressions are numeric	Subtraction
Either expression is NULL	NULL is returned
Both expressions are empty	Empty string is returned

variant_xor

(PHP 5)

variant_xor -- Performs a logical exclusion on two variants

Description

mixed variant_xor ( mixed left, mixed right )

Performs a logical exclusion, according to the following truth table:

Tabella 1. Variant XOR Rules

If `left` is	If `right` is	then the result is
`TRUE`	`TRUE`	`FALSE`
`TRUE`	`FALSE`	`TRUE`
`FALSE`	`TRUE`	`TRUE`
`FALSE`	`FALSE`	`FALSE`
`NULL`	`NULL`	`NULL`

Nota: As with all the variant arithmetic functions, the parameters for this function can be either a PHP native type (integer, string, floating point, boolean or NULL), or an instance of a COM, VARIANT or DOTNET class. PHP native types will be converted to variants using the same rules as found in the constructor for the VARIANT class. COM and DOTNET objects will have the value of their default property taken and used as the variant value.
The variant arithmetic functions are wrappers around the similarly named functions in the COM library; for more information on these functions, consult the MSDN library. The PHP functions are named slightly differently; for example variant_add() in PHP corresponds to VarAdd() in the MSDN documentation.

XVI. Funzioni di Crack

Introduzione

Queste funzioni permettono di usare la libreria CrackLib per testare la 'forza' di una password. La 'forza' di una password è testata attraverso un controllo sulla lunghezza, sull'uso di maiuscole e minuscole ed un controllo attraverso lo specifico dizionario di CrackLib. CrackLib darà anche utili messaggi diagnostici che aiuteranno nel 'rafforzare' la password.

Nota: Questo modulo è stato spostato nel repository PECL e non sarà più rilascio con il PHP dalla versione 5.0.0.

Requisiti

Maggiori informazioni riguardo CrackLib possono essere trovate, insieme alla libreria, a http://www.crypticide.com/users/alecm/.

Installazione

This PECL extension is not bundled with PHP. Additional information such as new releases, downloads, source files, maintainer information, and a CHANGELOG, can be located here: http://pecl.php.net/package/crack.

In PHP 4 this PECL extensions source can be found in the ext/ directory within the PHP source or at the PECL link above. Per potere utilizzare queste funzioni, occorre compilare il PHP con il supporto per Crack utilizzando --with-crack[=DIR] option.

Gli utenti di Windows dovranno abilitare php_crack.dll nel php.ini per potere utilizzare queste funzioni. In PHP 4 this DLL resides in the extensions/ directory within the PHP Windows binaries download. You may download this PECL extension DLL from the PHP Downloads page or at http://snaps.php.net/.

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

Tabella 1. Opzioni di configurazione per Crack

Nome	Default	Modificabile	Log modifiche
crack.default_dictionary	NULL	PHP_INI_SYSTEM	Disponibile da PHP 4.0.5.

Per maggiori dettagli sulle costanti PHP_INI_* vedere Appendice G.

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

Questa estensione non definisce alcuna costante.

Esempi

Questo esempio mostra come aprire un dizionario di CrackLib, testare una determinata password, recuperare ogni messaggio diagnostico e chiudere il dizionario.
Esempio 1. Esempio di CrackLib
<?php // Apre il dizionario di CrackLib $dizionario = crack_opendict('/usr/local/lib/pw_dict') or die('Incapace di aprire il dizionario di CrackLib'); // Esegue il controllo della password $controllo = controllo_crack($dizionario, 'gx9A2s0x'); // Recupera i messaggi $messaggio = crack_getlastmessage(); echo $messaggio; // 'password forte' // Chiude il dizionario crack_closedict($dizionario); ?>

Nota: Se crack_check() restituisce TRUE, crack_getlastmessage() restituirà 'password forte'.

Sommario
crack_check -- Effettua un controllo nascosto con la password data
crack_closedict -- Chiude un dizionario di CrackLib aperto
crack_getlastmessage -- Restituisce il messaggio dell'ultimo controllo nascosto
crack_opendict -- Apre un nuovo dizionario di CrackLib

(PHP 4 >= 4.0.5, PECL)

crack_opendict -- Apre un nuovo dizionario di CrackLib

Descrizione

resource crack_opendict ( string dizionario )

Restituisce un identificatore di risorsa dizionario in caso di successo, o FALSE in caso di fallimento.

Avvertimento

crack_opendict() apre il dizionario specificato di CrackLib per usarlo con crack_check().

Nota: Può essere aperto solo un dizionario alla volta.

Vedere anche: crack_check() e crack_closedict().

XVII. Funzioni di tipo dei caratteri

Introduzione

Le funzioni fornite da questa estensione controllano se un carattere o una stringa rientrano in una classe di caratteri in accordo con l'ambiente corrente (vedere anche setlocale()).

Quando vengono chiamate con un numero intero come argomento queste funzioni si comportano esattamente come il loro equivalente in C presente in ctype.h.

Quando vengono chiamate con una stringa come argomento controlleranno ogni carattere della stringa e ritorneranno TRUE se ogni carattere della stringa soddisfa il criterio richiesto. Quando sono eseguite con una stringa vuota il risultato è sempre TRUE

Passare qualsiasi cosa eccetto una stringa o un numero intero restituirà immediatamenente FALSE.

Requisiti

Nessuno oltre alle funzioni della libreria standard del C che sono sempre disponibili.

Installazione

A partire da PHP 4.2.0 queste funzioni sono abilitate di default. Per le versioni più vecchie bisogna configurare e compilare PHP con --enable-ctype.

La versione per Windows di PHP ha già compilato il supporto per questo modulo. Non occorre caricare alcun modulo addizionale per potere utilizzare queste funzioni.

Nota: Il supporto per CType pre-compilato è disponibile a partire dalla versione 4.3.0.

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

Questa estensione non definisce alcuna costante.

Sommario
ctype_alnum -- Controlla i caratteri alfanumerici
ctype_alpha -- Controlla i caratteri alfabetici
ctype_cntrl -- Controlla i caratteri di controllo
ctype_digit -- Controlla i caratteri numerici
ctype_graph -- Controlla ogni carattere stampabile tranne lo spazio
ctype_lower -- Controlla i caratteri minuscoli
ctype_print -- Controlla i caratteri stampabili
ctype_punct -- Controlla ogni carattere stampabile che non è uno spazio o un carattere alfanumerico
ctype_space -- Controlla gli spazi
ctype_upper -- Controlla i caratteri maiuscoli
ctype_xdigit -- Controlla i caratteri che rappresentano una cifra esadecimale

bool ctype_xdigit ( string testo )

Restituisce TRUE se ogni carattere di testo è una 'cifra' esadecimale, cioè una cifra decimale o un carattere fra [A-Fa-f] , FALSE in caso contrario.

Esempio 1. Esempio di uso di ctype_xdigit()
<?php $strings = array('AB10BC99', 'AR1012', 'ab12bc99'); foreach ($strings as $testcase) { if (ctype_xdigit($testcase)) { echo "The string $testcase consists of all hexadecimal digits.\n"; } else { echo "The string $testcase does not consist of all hexadecimal digits.\n"; } } ?>
Questo esempio visualizzerà :
The string AB10BC99 consists of all hexadecimal digits. The string AR1012 does not consist of all hexadecimal digits. The string ab12bc99 consists of all hexadecimal digits.

Vedere anche ctype_digit().

XVIII. Funzioni CURL, Client URL Library

Introduzione

PHP supporta libcurl, una libreria creata da Daniel Stenberg, che permette di collegarsi e comunicare con parecchi tipi di server e con parecchi tipi di protocolli. Libcurl al momento supporta i protocolli http, https, ftp, gopher, telnet, dict, file, e ldap. libcurl supporta anche i certificati HTTPS, HTTP POST, HTTP PUT, l'upload via FTP (questo può essere ottenuto anche con l'estensione ftp di PHP), upload attraverso una form HTTP, proxy, cookie e autenticazione con utente e password.

Queste funzioni sono state aggiunte in PHP 4.0.2.

Requisiti

Per utilizzare le funzioni CURL occorre installare il pacchetto CURL. PHP richiede che si usi CURL 7.0.2-beta o successivi. PHP non funzionerà con alcuna versione di CURL antecedente alla 7.0.2-beta. Dalla versione 4.2.3 di PHP è necessario usare CURL versione 7.9.0 o successiva. Con PHP 4.3.0 occorre avere CURL 7.9.8 o successive. PHP 5.0.0 molto probabilmente richiederà CURL 7.10.5 o successiva.

Installazione

Al fine di utilizzare il supporto CURL occorre anche compilare PHP con --with-curl[=DIR] dove DIR è il percorso della directory che contiene le directory lib e include. Nella directory "include" ci dovrebbe essere una cartella chiamata "curl" che dovrebbe contenere i file easy.h e curl.h. Ci dovrebbe essere un file chiamato libcurl.a nella directory "lib". A cominciare da PHP 4.3.0 si può configurare PHP all'uso di CURL per gli URL stream --with-curlwrappers.

Nota agli utenti Win32: Per abilitare questo modulo in ambiente Windows, occorre copiare libeay32.dll e ssleay32.dll dalla cartella delle DLL del pacchetto PHP/Win32 nella cartella SYSTEM32 della propria macchina Windows. (Es: C:\WINNT\SYSTEM32 o C:\WINDOWS\SYSTEM)

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

CURLOPT_DNS_USE_GLOBAL_CACHE (integer)

CURLOPT_DNS_CACHE_TIMEOUT (integer)

CURLOPT_FTPSSLAUTH (integer): Disponibile da PHP 5.1.0

CURLOPT_PORT (integer)

CURLOPT_FILE (integer)

CURLOPT_INFILE (integer)

CURLOPT_INFILESIZE (integer)

CURLOPT_URL (integer)

CURLOPT_PROXY (integer)

CURLOPT_VERBOSE (integer)

CURLOPT_HEADER (integer)

CURLOPT_HTTPHEADER (integer)

CURLOPT_NOPROGRESS (integer)

CURLOPT_NOBODY (integer)

CURLOPT_FAILONERROR (integer)

CURLOPT_UPLOAD (integer)

CURLOPT_POST (integer)

CURLOPT_FTPLISTONLY (integer)

CURLOPT_FTPAPPEND (integer)

CURLOPT_NETRC (integer)

CURLOPT_FOLLOWLOCATION (integer)

CURLOPT_FTPASCII (integer)

CURLOPT_PUT (integer)

CURLOPT_MUTE (integer)

CURLOPT_USERPWD (integer)

CURLOPT_PROXYUSERPWD (integer)

CURLOPT_RANGE (integer)

CURLOPT_TIMEOUT (integer)

CURLOPT_POSTFIELDS (integer)

CURLOPT_REFERER (integer)

CURLOPT_USERAGENT (integer)

CURLOPT_FTPPORT (integer)

CURLOPT_FTP_USE_EPSV (integer)

CURLOPT_LOW_SPEED_LIMIT (integer)

CURLOPT_LOW_SPEED_TIME (integer)

CURLOPT_RESUME_FROM (integer)

CURLOPT_COOKIE (integer)

CURLOPT_SSLCERT (integer)

CURLOPT_SSLCERTPASSWD (integer)

CURLOPT_WRITEHEADER (integer)

CURLOPT_SSL_VERIFYHOST (integer)

CURLOPT_COOKIEFILE (integer)

CURLOPT_SSLVERSION (integer)

CURLOPT_TIMECONDITION (integer)

CURLOPT_TIMEVALUE (integer)

CURLOPT_CUSTOMREQUEST (integer)

CURLOPT_STDERR (integer)

CURLOPT_TRANSFERTEXT (integer)

CURLOPT_RETURNTRANSFER (integer)

CURLOPT_QUOTE (integer)

CURLOPT_POSTQUOTE (integer)

CURLOPT_INTERFACE (integer)

CURLOPT_KRB4LEVEL (integer)

CURLOPT_HTTPPROXYTUNNEL (integer)

CURLOPT_FILETIME (integer)

CURLOPT_WRITEFUNCTION (integer)

CURLOPT_READFUNCTION (integer)

CURLOPT_PASSWDFUNCTION (integer)

CURLOPT_HEADERFUNCTION (integer)

CURLOPT_MAXREDIRS (integer)

CURLOPT_MAXCONNECTS (integer)

CURLOPT_CLOSEPOLICY (integer)

CURLOPT_FRESH_CONNECT (integer)

CURLOPT_FORBID_REUSE (integer)

CURLOPT_RANDOM_FILE (integer)

CURLOPT_EGDSOCKET (integer)

CURLOPT_CONNECTTIMEOUT (integer)

CURLOPT_SSL_VERIFYPEER (integer)

CURLOPT_CAINFO (integer)

CURLOPT_CAPATH (integer)

CURLOPT_COOKIEJAR (integer)

CURLOPT_SSL_CIPHER_LIST (integer)

CURLOPT_BINARYTRANSFER (integer)

CURLOPT_NOSIGNAL (integer)

CURLOPT_PROXYTYPE (integer)

CURLOPT_BUFFERSIZE (integer)

CURLOPT_HTTPGET (integer)

CURLOPT_HTTP_VERSION (integer)

CURLOPT_SSLKEY (integer)

CURLOPT_SSLKEYTYPE (integer)

CURLOPT_SSLKEYPASSWD (integer)

CURLOPT_SSLENGINE (integer)

CURLOPT_SSLENGINE_DEFAULT (integer)

CURLOPT_SSLCERTTYPE (integer)

CURLOPT_CRLF (integer)

CURLOPT_ENCODING (integer)

CURLOPT_PROXYPORT (integer)

CURLOPT_UNRESTRICTED_AUTH (integer)

CURLOPT_FTP_USE_EPRT (integer)

CURLOPT_HTTP200ALIASES (integer)

CURLOPT_HTTPAUTH (integer)

CURLAUTH_BASIC (integer)

CURLAUTH_DIGEST (integer)

CURLAUTH_GSSNEGOTIATE (integer)

CURLAUTH_NTLM (integer)

CURLAUTH_ANY (integer)

CURLAUTH_ANYSAFE (integer)

CURLOPT_PROXYAUTH (integer)

CURLCLOSEPOLICY_LEAST_RECENTLY_USED (integer)

CURLCLOSEPOLICY_LEAST_TRAFFIC (integer)

CURLCLOSEPOLICY_SLOWEST (integer)

CURLCLOSEPOLICY_CALLBACK (integer)

CURLCLOSEPOLICY_OLDEST (integer)

CURLINFO_EFFECTIVE_URL (integer)

CURLINFO_HTTP_CODE (integer)

CURLINFO_HEADER_SIZE (integer)

CURLINFO_REQUEST_SIZE (integer)

CURLINFO_TOTAL_TIME (integer)

CURLINFO_NAMELOOKUP_TIME (integer)

CURLINFO_CONNECT_TIME (integer)

CURLINFO_PRETRANSFER_TIME (integer)

CURLINFO_SIZE_UPLOAD (integer)

CURLINFO_SIZE_DOWNLOAD (integer)

CURLINFO_SPEED_DOWNLOAD (integer)

CURLINFO_SPEED_UPLOAD (integer)

CURLINFO_FILETIME (integer)

CURLINFO_SSL_VERIFYRESULT (integer)

CURLINFO_CONTENT_LENGTH_DOWNLOAD (integer)

CURLINFO_CONTENT_LENGTH_UPLOAD (integer)

CURLINFO_STARTTRANSFER_TIME (integer)

CURLINFO_CONTENT_TYPE (integer)

CURLINFO_REDIRECT_TIME (integer)

CURLINFO_REDIRECT_COUNT (integer)

CURL_VERSION_IPV6 (integer)

CURL_VERSION_KERBEROS4 (integer)

CURL_VERSION_SSL (integer)

CURL_VERSION_LIBZ (integer)

CURLVERSION_NOW (integer)

CURLE_OK (integer)

CURLE_UNSUPPORTED_PROTOCOL (integer)

CURLE_FAILED_INIT (integer)

CURLE_URL_MALFORMAT (integer)

CURLE_URL_MALFORMAT_USER (integer)

CURLE_COULDNT_RESOLVE_PROXY (integer)

CURLE_COULDNT_RESOLVE_HOST (integer)

CURLE_COULDNT_CONNECT (integer)

CURLE_FTP_WEIRD_SERVER_REPLY (integer)

CURLE_FTP_ACCESS_DENIED (integer)

CURLE_FTP_USER_PASSWORD_INCORRECT (integer)

CURLE_FTP_WEIRD_PASS_REPLY (integer)

CURLE_FTP_WEIRD_USER_REPLY (integer)

CURLE_FTP_WEIRD_PASV_REPLY (integer)

CURLE_FTP_WEIRD_227_FORMAT (integer)

CURLE_FTP_CANT_GET_HOST (integer)

CURLE_FTP_CANT_RECONNECT (integer)

CURLE_FTP_COULDNT_SET_BINARY (integer)

CURLE_PARTIAL_FILE (integer)

CURLE_FTP_COULDNT_RETR_FILE (integer)

CURLE_FTP_WRITE_ERROR (integer)

CURLE_FTP_QUOTE_ERROR (integer)

CURLE_HTTP_NOT_FOUND (integer)

CURLE_WRITE_ERROR (integer)

CURLE_MALFORMAT_USER (integer)

CURLE_FTP_COULDNT_STOR_FILE (integer)

CURLE_READ_ERROR (integer)

CURLE_OUT_OF_MEMORY (integer)

CURLE_OPERATION_TIMEOUTED (integer)

CURLE_FTP_COULDNT_SET_ASCII (integer)

CURLE_FTP_PORT_FAILED (integer)

CURLE_FTP_COULDNT_USE_REST (integer)

CURLE_FTP_COULDNT_GET_SIZE (integer)

CURLE_HTTP_RANGE_ERROR (integer)

CURLE_HTTP_POST_ERROR (integer)

CURLE_SSL_CONNECT_ERROR (integer)

CURLE_FTP_BAD_DOWNLOAD_RESUME (integer)

CURLE_FILE_COULDNT_READ_FILE (integer)

CURLE_LDAP_CANNOT_BIND (integer)

CURLE_LDAP_SEARCH_FAILED (integer)

CURLE_LIBRARY_NOT_FOUND (integer)

CURLE_FUNCTION_NOT_FOUND (integer)

CURLE_ABORTED_BY_CALLBACK (integer)

CURLE_BAD_FUNCTION_ARGUMENT (integer)

CURLE_BAD_CALLING_ORDER (integer)

CURLE_HTTP_PORT_FAILED (integer)

CURLE_BAD_PASSWORD_ENTERED (integer)

CURLE_TOO_MANY_REDIRECTS (integer)

CURLE_UNKNOWN_TELNET_OPTION (integer)

CURLE_TELNET_OPTION_SYNTAX (integer)

CURLE_OBSOLETE (integer)

CURLE_SSL_PEER_CERTIFICATE (integer)

CURLE_GOT_NOTHING (integer)

CURLE_SSL_ENGINE_NOTFOUND (integer)

CURLE_SSL_ENGINE_SETFAILED (integer)

CURLE_SEND_ERROR (integer)

CURLE_RECV_ERROR (integer)

CURLE_SHARE_IN_USE (integer)

CURLE_SSL_CERTPROBLEM (integer)

CURLE_SSL_CIPHER (integer)

CURLE_SSL_CACERT (integer)

CURLE_BAD_CONTENT_ENCODING (integer)

CURLE_LDAP_INVALID_URL (integer)

CURLE_FILESIZE_EXCEEDED (integer)

CURLFTPAUTH_DEFAULT (integer): Available since PHP 5.1.0

CURLFTPAUTH_SSL (integer): Available since PHP 5.1.0

CURLFTPAUTH_TLS (integer): Disponibile da PHP 5.1.0

CURLE_FTP_SSL_FAILED (integer)

CURLPROXY_HTTP (integer)

CURLPROXY_SOCKS5 (integer)

CURL_NETRC_OPTIONAL (integer)

CURL_NETRC_IGNORED (integer)

CURL_NETRC_REQUIRED (integer)

CURL_HTTP_VERSION_NONE (integer)

CURL_HTTP_VERSION_1_0 (integer)

CURL_HTTP_VERSION_1_1 (integer)

CURLM_CALL_MULTI_PERFORM (integer)

CURLM_OK (integer)

CURLM_BAD_HANDLE (integer)

CURLM_BAD_EASY_HANDLE (integer)

CURLM_OUT_OF_MEMORY (integer)

CURLM_INTERNAL_ERROR (integer)

CURLMSG_DONE (integer)

Esempi

Una volta compilato PHP con supporto CURL, si possono usare le funzioni CURL. L'idea di fondo che sta dietro le funzioni CURL è: si inizializza una sessione CURL usando curl_init(), si impostano le opzioni per il trasferimento tramite curl_setopt(), si esegue la sessione usando curl_exec() e quindi si termina la sessione con curl_close(). Qui di seguito si trova un esempio che fa uso delle funzioni CURL per scaricare la homepage del sito example.com e metterla in un file:
Esempio 1. Usare il modulo CURL di PHP per scaricare la homepage di example.com
<?php $ch = curl_init("http://www.example.com/"); $fp = fopen("example_homepage.txt", "w"); curl_setopt($ch, CURLOPT_FILE, $fp); curl_setopt($ch, CURLOPT_HEADER, 0); curl_exec($ch); curl_close($ch); fclose($fp); ?>

Sommario
curl_close -- Chiude una sessione CURL
curl_copy_handle -- Copy a cURL handle along with all of its preferences
curl_errno -- Restituisce il numero dell'ultimo errore
curl_error -- Restituisce una stringa contenente l'ultimo errore relativo alla sessione corrente
curl_exec -- Esegue una sessione CURL
curl_getinfo -- Ottiene informazioni relative a un determinato trasferimento
curl_init -- Inizializza una sessione CURL
curl_multi_add_handle -- Aggiunge un handle cURL ad un multi handle cURL
curl_multi_close -- Chiude un set di handle cURL
curl_multi_exec -- Esegue la sotto-connessione dell'handle cURL corrente
curl_multi_getcontent -- Restituisce il contenuto di un handle cURL se è impostato CURLOPT_RETURNTRANSFER
curl_multi_info_read -- Ottiene informazioni sui trasferimenti correnti
curl_multi_init -- Restituisce un nuovo multi handle cURL
curl_multi_remove_handle -- Rimuove un multi handle da un set di handle cURL
curl_multi_select -- Restituisce tutti i socket associati alla estensione cURL che possono essere "selected"
curl_setopt -- Imposta una opzione per un trasferimento CURL
curl_version -- Restituisce la versione di CURL in uso

curl_close

(PHP 4 >= 4.0.2, PHP 5)

curl_close -- Chiude una sessione CURL

Descrizione

void curl_close ( resource ch )

Questa funzione chiude una sessione CURL e libera tutte le risorse. L'handle CURL ch viene anch'esso eliminato.

Esempio 1. Inizializza una sessione CURL e scarica una pagina
<?php // crea una risorsa curl $ch = curl_init(); // imposta l'URL e le opzioni appropriate curl_setopt($ch, CURLOPT_URL, "http://www.example.com/"); curl_setopt($ch, CURLOPT_HEADER, 0); // scarica l'URL e lo passa al browser curl_exec($ch); // chiude la risorsa curl curl_close($ch); ?>

Vedere anche: curl_init().

curl_copy_handle

(PHP 5)

curl_copy_handle -- Copy a cURL handle along with all of its preferences

Description

resource curl_copy_handle ( resource ch )

This function copies a cURL handle, returning a new cURL handle with the same preferences.

Esempio 1. Copying a cURL handle.
<?php // create a new curl resource $ch = curl_init(); // set URL and other appropriate options curl_setopt($ch, CURLOPT_URL, 'http://www.example.com/'); curl_setopt($ch, CURLOPT_HEADER, 0); // copy the handle $ch2 = curl_copy_handle($ch); // grab URL (http://www.example.com/) and pass it to the browser curl_exec($ch2); // close curl resources, and free up system resources curl_close($ch2); curl_close($ch); ?>

curl_errno

(PHP 4 >= 4.0.3, PHP 5)

curl_errno -- Restituisce il numero dell'ultimo errore

Descrizione

int curl_errno ( resource ch )

La funzione resituisce il numero dell'errore per l'ultima operazione cURL sulla risorsa ch, oppure 0 (zero) se non vi sono errori.

Vedere anche curl_error() e I codici di errore CURL.

curl_error

(PHP 4 >= 4.0.3, PHP 5)

curl_error -- Restituisce una stringa contenente l'ultimo errore relativo alla sessione corrente

Descrizione

string curl_error ( resource ch )

La funzione restituisce un messaggio di errore testuale per l'ultima operazione cURL eseguita sulla risorsa ch, oppure '' (una stringa vuota) se non vi sono errori.

Vedere anche curl_errno() e Codici di errore CURL.

curl_exec

(PHP 4 >= 4.0.2, PHP 5)

curl_exec -- Esegue una sessione CURL

Descrizione

mixed curl_exec ( resource ch )

Questa funzione deve essere chiamata dopo aver inizializzato una sessione CURL e dopo che tutte le opzioni per la sessione sono state impostate. La sua funzione è semplicemente quella di eseguire la sessione CURL predefinita (identificata dal parametro ch).
Esempio 1. Inizializza una sessione CURL e scarica una pagina web.
<?php // Crea la risorsa CURL $ch = curl_init(); // Imposta l'URL e altre opzioni curl_setopt($ch, CURLOPT_URL, "http://www.example.com/"); curl_setopt($ch, CURLOPT_HEADER, 0); // Scarica l'URL e lo passa al browser curl_exec($ch); // Chiude la risorsa curl curl_close($ch); ?>

Nota: Se si desidera avere restituito il risultato anzichè averlo visualizzato direttamente sul browser, utilizzare l'opzione CURLOPT_RETURNTRANSFER di curl_setopt().

curl_getinfo

(PHP 4 >= 4.0.4, PHP 5)

curl_getinfo -- Ottiene informazioni relative a un determinato trasferimento

Descrizione

string curl_getinfo ( resource ch [, int opt] )

La funzione restituisce informazioni sull'ultimo trasferimento, il parametro opt può assumere uno dei seguenti valori:

"CURLINFO_EFFECTIVE_URL" - L'ultimo URL reale
"CURLINFO_HTTP_CODE" - L'ultimo codice HTTP ricevuto
"CURLINFO_FILETIME" - Data del documento remoto ricevuto, -1 indica che la data del documento è sconosciuta
"CURLINFO_TOTAL_TIME" - Tempo totale in secondi per l'ultimo trasferimento
"CURLINFO_NAMELOOKUP_TIME" - Tempo in secondi impiegato per risolvere il nome
"CURLINFO_CONNECT_TIME" - Tempo in secondi necessario per stabilire la connessione
"CURLINFO_PRETRANSFER_TIME" - Tempo in secondi dall'inizio fino a prima di cominciare il trasferimento
"CURLINFO_STARTTRANSFER_TIME" - Tempo in secondi fino a quando comincia il trasferimento del primo byte
"CURLINFO_REDIRECT_TIME" - Tempo in secondi richiesto dai passi di redirezione prima che sia cominciata la transazione finale
"CURLINFO_SIZE_UPLOAD" - Numero totale dei byte inviati
"CURLINFO_SIZE_DOWNLOAD" - Numero totale dei byte scaricati
"CURLINFO_SPEED_DOWNLOAD" - Velocità media di download
"CURLINFO_SPEED_UPLOAD" - Velocità media di upload
"CURLINFO_HEADER_SIZE" - Dimensione totale di tutte le header ricevute
"CURLINFO_REQUEST_SIZE" - Dimensione totale delle richieste, attualmente solo per le richieste HTTP
"CURLINFO_SSL_VERIFYRESULT" - Risultato delle verifiche del certificato richieste da CURLOPT_SSL_VERIFYPEER
"CURLINFO_CONTENT_LENGTH_DOWNLOAD" - Lunghezza del download ottenuta dal campo Content-Length:
"CURLINFO_CONTENT_LENGTH_UPLOAD" - Dimensione specificata dell'upload
"CURLINFO_CONTENT_TYPE" - Content-type dell'oggetto scaricato, il valore NULL indica che il server non ha inviato un Content-Type: valido

Se la funzione viene eseguita senza il parametro opzionale opt, sarà restituito un array contenente i seguenti elementi corrispondenti alle opzioni di opt:

"url"
"content_type"
"http_code"
"header_size"
"request_size"
"filetime"
"ssl_verify_result"
"redirect_count"
"total_time"
"namelookup_time"
"connect_time"
"pretransfer_time"
"size_upload"
"size_download"
"speed_download"
"speed_upload"
"download_content_length"
"upload_content_length"
"starttransfer_time"
"redirect_time"

curl_init

(PHP 4 >= 4.0.2, PHP 5)

curl_init -- Inizializza una sessione CURL

bool curl_setopt ( resource ch, int option, mixed valore )

Imposta le opzioni per una sessione CURL identificata dal parametro ch. opzione specifica quale opzione impostare e valore specifica il valore per l'opzione data.

valore dovrebbe essere di tipo booleano per i seguenti valori del parametro opzione):

Option	Set `value` to	Notes
`CURLOPT_BINARYTRANSFER`	`TRUE` restituisce la riga di output quando `CURLOPT_RETURNTRANSFER` è usata.
`CURLOPT_CRLF`	`TRUE` per convertire la Unix newlines in CRLF newlines per i trasferimenti.
`CURLOPT_DNS_USE_GLOBAL_CACHE`	`TRUE` per usare una cache gobale DNS. Questa opzione non è thread-safe ed è abilitata per default.
`CURLOPT_FAILONERROR`	`TRUE` per terminare in maniera silenziosa se il codice HTTP restituito è maggiore di 300. Il comportamento di default è di restituire la pagina normalmente, ignorando il codice.
`CURLOPT_FILETIME`	`TRUE` per cercare di recuperare la data di modifica del documento remoto. Si può cercare di ripristinare questo valore usando l'opzione `CURLINFO_FILETIME` con curl_getinfo().
`CURLOPT_FOLLOWLOCATION`	`TRUE` per seguire una qualunque `"Location: "` intestazione inviata dal server come parte dell' header HTTP (notare che è ricorsiva, PHP seguirà come molte `"Location: "` intestazioni inviate, a meno che `CURLOPT_MAXREDIRS` sia impostata).
`CURLOPT_FORBID_REUSE`	`TRUE` forza la chiusura esplicita della connessione quando ha finito il processo e non può essere riutilizzata.
`CURLOPT_FRESH_CONNECT`	`TRUE` forza l'uso di una nuova connessione invece di usarne una in cache.
`CURLOPT_FTP_USE_EPRT`	`TRUE` per usare EPRT (e LPRT) quando si opera un download FTP. Usa `FALSE` per disaibilitare EPRT e LPRT e usare PORT solamente.
`CURLOPT_FTP_USE_EPSV`	`TRUE` prima cerca un comando EPSV per trasferimento FTP prima di ritornare alla modalità PASV. Imposta a `FALSE` per disabilitare EPSV.
`CURLOPT_FTPAPPEND`	`TRUE` per accodare aò file remoto invece di sovrascriverlo.
`CURLOPT_FTPASCII`	Un alias di `CURLOPT_TRANSFERTEXT`. Usarlo al suo posto.
`CURLOPT_FTPLISTONLY`	`TRUE` per elencare solamente i nomi di una directory FTP.
`CURLOPT_HEADER`	`TRUE` per includere l'intestazione in output.
`CURLOPT_HTTPGET`	`TRUE` per resettare la richiesta HTTP col metodo GET. Dopo che GET è il default, diventa necessario solo se il metodo di richiesta è cambiato.
`CURLOPT_HTTPPROXYTUNNEL`	`TRUE` per passare attraverso un proxy HTTP fornito.
`CURLOPT_MUTE`	`TRUE` per essere totalemtne silenzioso nei riguardi di una funzione CURL.
`CURLOPT_NETRC`	`TRUE` per condurre il file `~/.netrc` a trovare username e password per il sito remoto col quale si stabilisce una connessione.
`CURLOPT_NOBODY`	`TRUE` esclude il corpo dall'output.
`CURLOPT_NOPROGRESS`	`TRUE` per disabilitare il progress meter per trasferimetni CURL. Nota: PHP automaticamente imposta questa opzione a `TRUE` dovrebbe essere cambiata solo per operazioni di debug.
`CURLOPT_NOSIGNAL`	`TRUE` per ignorare qualunque funzione CURL che causa l'invio di un segnale a un processo PHP. Ciò è settato come default con le multi-threaded SAPI in modo che le opzioni di timeout possano essere ancora usate.	Aggiunto in CURL 7.10.
`CURLOPT_POST`	`TRUE` per compiere un regolare HTTP POST. Questo POST è il tipo normale di `application/x-www-form-urlencoded`, più comunemente usata dai form HTML.
`CURLOPT_PUT`	`TRUE` per HTTP PUT un file. Il file da PUT deve essere impostato con `CURLOPT_INFILE` e `CURLOPT_INFILESIZE`.
`CURLOPT_RETURNTRANSFER`	`TRUE` per restituire il trasferimento come una stringa del valore restituito di curl_exec() al posto di metterlo in output direttamente.
`CURLOPT_SSL_VERIFYPEER`	`FALSE` per fermare CURL dal verificare i certificati dei peer. Un certificato alternativo di verificare può essere specificato con l'opzione `CURLOPT_CAINFO` o una directory certificata può essere specificata con l'opzione `CURLOPT_CAPATH` . `CURLOPT_SSL_VERIFYHOST` può anche dover essere messa `TRUE` o `FALSE` se `CURLOPT_SSL_VERIFYPEER` è disabilitata (il default è 2).	`TRUE` per default nel CURL 7.10. Default bundle installed as of CURL 7.10.
`CURLOPT_TRANSFERTEXT`	`TRUE` per usare la modalità ASCII per trasferimenti FTP. Per LDAP, riporta i dati in testo iano invece che in HTML. Sui sistemi Windows, non imposterà `STDOUT` alla modalità binaria.
`CURLOPT_UNRESTRICTED_AUTH`	`TRUE` invia username e password quando le seguenti locazioni (che usano `CURLOPT_FOLLOWLOCATION`), anche quando l'hostname è cambiato.
`CURLOPT_UPLOAD`	`TRUE` per preparare un upload.
`CURLOPT_VERBOSE`	`TRUE` per inviare un'informazione di tipo verbose. Scrive l'output su `STDERR`, o sul file specificato usando `CURLOPT_STDERR`.

value dovrebbe essere un intero per i seguenti valori del parametro option :

Option	Set `value` to	Notes
`CURLOPT_BUFFERSIZE`	La dimensione del buffer da utilizzare per ogni lettura. Non è garantito che questa richiesta venga soddisfatta, comunque.	Aggiunto in CURL 7.10.
`CURLOPT_CLOSEPOLICY`	Anche `CURLCLOSEPOLICY_LEAST_RECENTLY_USED` or `CURLCLOSEPOLICY_OLDEST`. Ci sono altri tre `CURLCLOSEPOLICY_` costanti, ma CURL non li supporta ancora.
`CURLOPT_CONNECTTIMEOUT`	Il numero di secondi da aspettare mentre si cerca di connettersi. Usare 0 per aspettare indefinitamente.
`CURLOPT_DNS_CACHE_TIMEOUT`	Il numero di secondi con cui mantenere le istanze DNS in memoria. Questa opzio è posta a 120 (2 minuti) per default.
`CURLOPT_FTPSSLAUTH`	Il metodo di autenticazione FTP (quando attivato): `CURLFTPAUTH_SSL` (cerca per primo SSL), `CURLFTPAUTH_TLS` (cerca per primo SSL), o `CURLFTPAUTH_DEFAULT` (lascia decidere a CURL).	Aggiunto in CURL 7.12.2 e disponibile da PHP 5.1.0
`CURLOPT_HTTP_VERSION`	`CURL_HTTP_VERSION_NONE` (default, lascia decidere CURL quale versione usare), `CURL_HTTP_VERSION_1_0` (forza HTTP/1.0), o `CURL_HTTP_VERSION_1_1` (forza HTTP/1.1).
`CURLOPT_HTTPAUTH`	Il metodo(i) di autenticazione HTTP da usare. Le opzioni sono: `CURLAUTH_BASIC`, `CURLAUTH_DIGEST`, `CURLAUTH_GSSNEGOTIATE`, `CURLAUTH_NTLM`, `CURLAUTH_ANY`, e `CURLAUTH_ANYSAFE`. Si può usre l'operatore binario `\|` (or) per combinare più di un metodo. In questo caso, CURL testerà il server per vedere quali metodi esso supporta e sceglierà il migliore. `CURLAUTH_ANY` è un alias per `CURLAUTH_BASIC \| CURLAUTH_DIGEST \| CURLAUTH_GSSNEGOTIATE \| CURLAUTH_NTLM`. `CURLAUTH_ANYSAFE` è un alias per `CURLAUTH_DIGEST \| CURLAUTH_GSSNEGOTIATE \| CURLAUTH_NTLM`.
`CURLOPT_INFILESIZE`	La grandezza attesa, in bytes, del file quando si invia (upload) un file a un sito remoto.
`CURLOPT_LOW_SPEED_LIMIT`	La velocità di trasferimento, in bytes al secondo, in cui la trasmissione dovrebbe stare al di sotto durante `CURLOPT_LOW_SPEED_TIME` secondi affinchè PHP to consideri la trasmissione troppo lenta e la abortisca.
`CURLOPT_LOW_SPEED_TIME`	Il numero di secondi in cui il trasferimento dovrebbe stare al di sotto `CURLOPT_LOW_SPEED_LIMIT` in modo che PHP consideri la rasmisiosne troppo lenta e la abortisca.
`CURLOPT_MAXCONNECTS`	L'ammontare massimo di connessioni persistenti consentite. Quando il limite è raggiunto, `CURLOPT_CLOSEPOLICY` viene usata per determinare quale connessione chiudere.
`CURLOPT_MAXREDIRS`	L'ammontare massimo di redirezioni HTTP da seguire. Usare questa opzione insieme a `CURLOPT_FOLLOWLOCATION`.
`CURLOPT_PORT`	Un numero di porta alternativo a cui connettersi.
`CURLOPT_PROXYAUTH`	Il metodo di autenticazione HTTP da usare per la connessione al proxy. Usare la stessa bitmask come descritto in in `CURLOPT_HTTPAUTH`. Per l'autenticazione del proxy, solo `CURLAUTH_BASIC` e `CURLAUTH_NTLM` sono attualmente supportate.	Aggiunto in CURL 7.10.7 e PHP 5.1.0.
`CURLOPT_PROXYPORT`	Il numero di porta del proxy alla quale connettersi. Questo numero può essere anche impostato in `CURLOPT_PROXY`.
`CURLOPT_PROXYTYPE`	Anche `CURLPROXY_HTTP` (default) o `CURLPROXY_SOCKS5`.	Aggiunto in CURL 7.10.
`CURLOPT_RESUME_FROM`	L' offset, in byte, per ripristinare un trasferimento.
`CURLOPT_SSL_VERIFYHOST`	1 per verificare l'esistenza di un nome comune nel certificato SSL peer . 2 per verificare l'esistenza di un nome comune e verificare inoltre che soddisfi l'hostname fornito.
`CURLOPT_SSLVERSION`	La versione SSL (2 or 3) da usare. Per default PHP cercherà di determinare ciò da se stesso, benchè in alcuni casi si possa impostarlo manualmente.
`CURLOPT_TIMECONDITION`	Come `CURLOPT_TIMEVALUE` è trattato. Usare `CURL_TIMECOND_IFMODSINCE` per restituire la pagina solo se è stata mpdificata dalla data specificata in `CURLOPT_TIMEVALUE`. Se non è stata modificata, un `"304 Not Modified"` header sarà restituito assumendo che `CURLOPT_HEADER` è `TRUE`. Usare `CURL_TIMECOND_ISUNMODSINCE` per l'effetto opposto. `CURL_TIMECOND_IFMODSINCE` è il default.	Aggiunto in PHP 5.1.0.
`CURLOPT_TIMEOUT`	Il numero massimo di secondi per permettere alle funzioni CURL di essere eseguite.
`CURLOPT_TIMEVALUE`	Il tempo in secondi dal 1 Gennaio 1970. Il tempo verrà usato da `CURLOPT_TIMECONDITION`. Per default, `CURL_TIMECOND_IFMODSINCE` è usato.

value dovrebbe essere una stringa per i seguenti valori del parametro option :

Option	Set `value` to	Notes
`CURLOPT_CAINFO`	Il nome di un file contenente uno o più certificati che verificano la parità. Ciò ha significato solo quando usato in combinazione con `CURLOPT_SSL_VERIFYPEER`.
`CURLOPT_CAPATH`	Una directory che contiene certificati multipli CA. Usare questa opzione insieme a `CURLOPT_SSL_VERIFYPEER`.
`CURLOPT_COOKIE`	The contents of the `"Set-Cookie: "` header to be used in the HTTP request.
`CURLOPT_COOKIEFILE`	Il nome del file che contiene i dati del cookie. Il cookie può essere nel formato Netscape, o solo un semplice header HTTP-style allegato in un file.
`CURLOPT_COOKIEJAR`	Il nome di un file in cui salvare tutti i cookie interni finchè la connessione termina.
`CURLOPT_CUSTOMREQUEST`	Un metodo custom di richiesta da usare al posto di `"GET"` o `"HEAD"` quando avviene una richiesta HTTP. Ciò è utile per un `"DELETE"` o altro, in più nasconde le richieste HTTP. Valori validi sono termini quali `"GET"`, `"POST"`, `"CONNECT"` e così via; i.e. Non inserire un'intera riga di richieste HTTP qui. Ad esempio, scrivere `"GET /index.html HTTP/1.0\r\n\r\n"` sarebbe errato. Nota: Non fare ciò senza essere sicuri che innanzitutto il vostro server supporti il metodo di richiesta custom.
`CURLOPT_EGBSOCKET`	Come `CURLOPT_RANDOM_FILE`, ecetto un filename per un Entropy Gathering Daemon socket.
`CURLOPT_ENCODING`	I contenuti di un' `"Accept-Encoding: "` header. Ciò abilita la decodifica della risposta. Termini supportati sono `"identity"`, `"deflate"`, e `"gzip"`. Se viene impostata una stringa vuota, `""`, viene inviato un header contenente tutti i tipi di termini supportati.
`CURLOPT_FTPPORT`	Il valore che verrà utilizzato per ottenere un indirizzo IP da usare per l'istruzione FTP "POST" . L'istruzione "POST" indica al server remoto il proprio indirizzo IP a cui connettersi. La stringa può essere un semplice indirizzo IP, un hostname, un nome di un'interfaccia di rete (sotto Unix), o un semplice '-' per usare l'indirizzo Ip del sistema di default.
`CURLOPT_INTERFACE`	Il nome di un'interfaccia di rete di uscita da usare. Può essere il nome di un'interfaccia, un indirizzo IP o un host name.
`CURLOPT_KRB4LEVEL`	Il livello di sicurezza KRB4 (Kerberos 4). Uno qualunque dei valori seguenti (in ordine dal meno al più significativo) sono validi: `"clear"`, `"safe"`, `"confidential"`, `"private".`. Se la stringa non corrisponde a uno di questi, si usa `"private"`. Impostando questa opzione a `NULL` disabilita la sicurezza KRB4. Attualmente la sicurezza KRB4 lavora solamente con transazioni FTP.
`CURLOPT_POSTFIELDS`	I dati completi da mandare in post in un'operazione HTTP "POST" .
`CURLOPT_PROXY`	Il proxy HTTP in cui veicolare le richieste.
`CURLOPT_PROXYUSERPWD`	Username e password formattate come `"[username]:[password]"` da usare per la connessione al proxy.
`CURLOPT_RANDOM_FILE`	IL nome del file da passare al generatore di numeri casuali per SSL.
`CURLOPT_RANGE`	Intervallo(i) di dati da ricevere nel formato `"X-Y"` dove X o Y sono opzionali. I trasferimenti HTTP supportano inoltre svariati intervalli, separati da virgole nel formato `"X-Y,N-M"`.
`CURLOPT_REFERER`	Il contenuto dell'header `"Referer: "` da usare in una richiesta HTTP.
`CURLOPT_SSL_CIPHER_LIST`	Elenco di cifre da usare con SSL. Per esempio, `RC4-SHA` e `TLSv1` sono elenchi validi di cifre.
`CURLOPT_SSLCERT`	Il nome di un file contenente un certificato PEM formattato.
`CURLOPT_SSLCERTPASSWD`	La password richiesta per usare il `CURLOPT_SSLCERT` certificato.
`CURLOPT_SSLCERTTYPE`	Il formato del certificato. Formati ammessi sono `"PEM"` (default), `"DER"`, e `"ENG"`.	Aggiunto in CURL 7.9.3.
`CURLOPT_SSLENGINE`	L' identificatore per il cripto-motore della chiave privata SSL specificata in `CURLOPT_SSLKEY`.
`CURLOPT_SSLENGINE_DEFAULT`	L' identificatore per il motore crypto usato per cripto-operazioni asimmetriche.
`CURLOPT_SSLKEY`	Il nome di un file contenente una chiave privata SSL.
`CURLOPT_SSLKEYPASSWD`	La password segreta necessaria per usare la chiave privata SSL specificata in `CURLOPT_SSLKEY`. Nota: Siccome questa opzione contiene una password di tipo sensitive, bisogna ricordarsi di mantenere lo script PHP, in cui è contenuto, sicuro.
`CURLOPT_SSLKEYTYPE`	Il tipo di chiave della chiave privata SSL specificata in `CURLOPT_SSLKEY`. I tipi di chiavi supportate sono `"PEM"` (default), `"DER"`, e `"ENG"`.
`CURLOPT_URL`	L' URL da raggiungere. E' possibnile impostarla quando si inizializza una sessione con curl_init().
`CURLOPT_USERAGENT`	I contenuti dell'header `"User-Agent: "` da usare in una richiesta HTTP.
`CURLOPT_USERPWD`	Username e password formattate come `"[username]:[password]"` da usare per la connessione.

value dovrebbe essere un array per i seguenti valori del parametro option :

Option	Set `value` to	Notes
`CURLOPT_HTTP200ALIASES`	Un array di 200 risposte HTTP che saranno trattate come risposte valide e non come errori.	Aggiunto in CURL 7.10.3.
`CURLOPT_HTTPHEADER`	Un array di campi di header HTTP da impostare.
`CURLOPT_POSTQUOTE`	Un array di comandi FTP da eseguire sul server dopo che la richiesta FTP è stata eseguita.
`CURLOPT_QUOTE`	Un array di comandi FTP commands da eseguire sul server prima della richiesta FTP.

value dovrebbe essere una risorsa di streaming (usando fopen(), per esempio) per i seguenti valori del parametro option :

Option	Set `value` to	Notes
`CURLOPT_FILE`	Il file che il trasferimento dovrebbe scrivere. Il default è `STDOUT` (la finestra del browser).
`CURLOPT_INFILE`	Il file ce il trasferimento dovrebbe leggere quando si fa un upload.
`CURLOPT_STDERR`	Una locazione alternativa per gli errori di output al posto di `STDERR`.
`CURLOPT_WRITEHEADER`	Il file su cui viene scritto l' header parte del trasferimento.

value dovrebbe essere una stringa col nome di una funzione di callback valida per i seguenti valori del parametro option :

Option	Set `value` to	Notes
`CURLOPT_HEADERFUNCTION`	Il nome della funzione di callback la quale prende due parametri. il primo è la risorsa CURL, il secondo è una stringa con i dati dell'header da scrivere. Usando questa funzione di callback, diventa propria la responsabilità di scrivere i dati di header. Restituisce il numero di bytes scritti.
`CURLOPT_PASSWDFUNCTION`	Il nome della funzione di callback che prende tre parametri. Il primo è la risorsa CURL, il secondo è una stringa contenente la richiesta di password e il terzo è la lunghezza massima della password. Restituisce la stringa che contiene la password.
`CURLOPT_READFUNCTION`	Il nome della funzione di callback che prende due parametri. Il primo è la risorsa CURL, e il secondo è una stringa con i dati da leggere. Usindo questa funzione di callback, diventa propria la responsabilità di leggere i dati. Restituisce il numero di bytes letti. Restituisce 0 per un segnale di `EOF`.
`CURLOPT_WRITEFUNCTION`	Il nome della funzione di callback che prende due parametri. Il primo è la risorsa CURL, e il secondo è una stringa con i dati da scrivere. Usindo questa funzione di callback, diventa propria la responsabilità di scrivere i dati. Deve restituire l'esatto numero di bytes scritti altrimenti fallisce.

Esempio 1. Inizializza una sessione CURL nuova e carica una pagina web
<?php // crea una nuova risorsa CURL $ch = curl_init(); // imposta l'URL e altre opzioni spedifiche curl_setopt($ch, CURLOPT_URL, "http://www.example.com/"); curl_setopt($ch, CURLOPT_HEADER, false); // carica l' URL e la passa al browser curl_exec($ch); // chiude la risorsa CURL e rilascia le risorse di sistema curl_close($ch); ?>

curl_version

(PHP 4 >= 4.0.2, PHP 5)

curl_version -- Restituisce la versione di CURL in uso

Descrizione

string curl_version ( [int version] )

La funzione curl_version() restituisce una stringa contenente la versione di CURL attualmente in uso.

XIX. Funzioni di pagamento Cybercash

Installazione

Queste funzione sono disponibili solo se l'interprete è stato compilato con l'opzione --with-cybercash=[DIR].

A partire da PHP 4.3.0 questo modulo è stato spostato, ed ora è reperibile in PECL.

Se si hanno dubbi sullo stato di CyberCash vedere CyberCash Faq In breve, CyberCash è stato acquisito da VeriSign e, sebbene il servizio CyberCash continui ad esistere, VeriSign incoraggia gli utenti a spostarsi. Vedere la faq precedente e PECL per dettagli.

Sommario
cybercash_base64_decode -- Decodifica dei dati in base64 per Cybercash
cybercash_base64_encode -- Codifica dei dati in base64 per Cybercash
cybercash_decr -- Decrifrazione Cybercash
cybercash_encr -- Criptazione Cybercash

La funzione restituisce un array associativo con gli elementi "errcode" e, se "errcode" è FALSE, "outbuff" (stringa), "outLth" (long) and "macbuff" (stringa).

cybercash_encr

(PHP 4 <= 4.2.3, PECL)

cybercash_encr -- Criptazione Cybercash

Descrizione

array cybercash_encr ( string wmk, string sk, string inbuff )

La funzione restituisce un array associativo con gli elementi "errcode" e, se "errcode" è FALSE, "outbuff" (stringa), "outLth" (long) and "macbuff" (stringa).

XX. Crédit Mutuel CyberMUT functions

Questa estensione vi permette di processare le transazioni delle carte di credito usando il sistema Crédit Mutuel CyberMUT (http://www.creditmutuel.fr/centre_commercial/vendez_sur_internet.html).

CynerMUT, in Francia, è un popolare servizio di pagamento tramite web, fornito dalla banca Crédit Mutuel. Se siete stranieri in Francia, queste funzioni non saranno utili.

Queste funzioni sono disponibili se PHP è stato compilato con l'opzione --with-cybermut[=DIR], dove DIR è la locazione di libcm-mac.a e cm-mac.h. Verrà richiesto l'appropriato SDK per la piattaforma, che sarà spedito dopo la sottoscrizione al servizio CyberMUT (contattateli via Web, o recatevi presso il più vicino Crédit Mutuel).

L'uso di queste funzioni è abbastanza simile alle funzioni originali, ad eccezione dei parametri restituiti da cybermut_creerformulairecm() e cybermut_creerreponsecm(), che sono restituiti direttamente dalle funzioni PHP, mentre loro sono passati in riferimento nelle funzioni originali.

Queste funzioni sono state aggiunte in PHP 4.0.6.

Nota: Queste funzioni forniscono solo un link all'SDK di CyberMUT. Assicuratevi di leggere la Guida per gli Sviluppatori del CyberMUT per i dettagli completi dei parametri richiesti.

Sommario
cybermut_creerformulairecm -- Genera un form HTML per la richiesta di pagamento
cybermut_creerreponsecm -- Genera la conferma della consegna della conferma di pagamento
cybermut_testmac -- Assicura che non siano contenuti dati manipolati nel messaggio di conferma ricevuto

cybermut_creerformulairecm

(4.0.5 - 4.2.3 only, PECL)

cybermut_creerformulairecm -- Genera un form HTML per la richiesta di pagamento

Descrizione

string cybermut_creerformulairecm ( string url_CM, string version, string TPE, string montant, string ref_commande, string texte_libre, string url_retour, string url_retour_ok, string url_retour_err, string langue, string code_societe, string texte_bouton )

cybermut_creerformulairecm() è usato per generare il form HTML per la richiesta di pagamento.

Esempio 1. Primo passo di pagamento (equiv cgi1.c)

<?php
// Directory dove si trovano le chiavi
putenv("CMKEYDIR=/var/creditmut/cles");
 
// Numero Versione
$VERSION="1.2";

  $retour =  cybermut_creerformulairecm(
  "https://www.creditmutuel.fr/test/telepaiement/paiement.cgi",
  $VERSION,
  "1234567890",
  "300FRF",
  $REFERENCE,
  $TEXTE_LIBRE,
  $URL_RETOUR,
  $URL_RETOUR_OK,
  $URL_RETOUR_ERR,
  "francais",
  "company",
  "Paiement par carte bancaire");
 
  echo $retour;                                                               
?>

Vedere anche cybermut_testmac() e cybermut_creerreponsecm().

cybermut_creerreponsecm

(4.0.5 - 4.2.3 only, PECL)

cybermut_creerreponsecm -- Genera la conferma della consegna della conferma di pagamento

Descrizione

string cybermut_creerreponsecm ( string phrase )

cybermut_creerreponsecm() restituisce una stringa contenente un messaggio di conferma di consegna.

Il parametro è "OK" se il messaggio di conferma del pagamento è stato correttamente autenticato da cybermut_testmac(). Ogni altra catena è considerata come un messaggio di errore.

Vedere anche cybermut_creerformulairecm() e cybermut_testmac().

cybermut_testmac

(4.0.5 - 4.2.3 only, PECL)

cybermut_testmac -- Assicura che non siano contenuti dati manipolati nel messaggio di conferma ricevuto

Descrizione

bool cybermut_testmac ( string code_MAC, string version, string TPE, string cdate, string montant, string ref_commande, string texte_libre, string code-retour )

cybermut_testmac() è usato per assicurare che non siano contenuti dati manipolati nel messaggio di conferma ricevuto. Prestate attenzione ai parametri code-retour e texte-libre, che non possono essere valutati tal quali, a causa del trattino. Dovete recuperarli usando:
<?php $code_retour=$HTTP_GET_VARS["code-retour"]; $texte_libre=$HTTP_GET_VARS["texte-libre"]; ?>

Esempio 1. Ultimo passaggio del pagamento (equiv cgi2.c)

<?php
// Make sure that Enable Track Vars is ON.
// Directory where are located the keys
putenv("CMKEYDIR=/var/creditmut/cles");
 
// Version number
$VERSION="1.2";

$texte_libre = $HTTP_GET_VARS["texte-libre"];
$code_retour = $HTTP_GET_VARS["code-retour"];                                     

$mac_ok = cybermut_testmac($MAC,$VERSION,$TPE,$date,$montant,$reference,$texte_libre,$code_retour);

if ($mac_ok) {

  //
  // insert data processing here
  //
  //

  $result=cybermut_creerreponsecm("OK");
} else {
  $result=cybermut_creerreponsecm("Document Falsifie");
}
 
?>

Vedere anche cybermut_creerformulairecm() e cybermut_creerreponsecm().

XXI. Funzioni di amministrazione Cyrus IMAP

Introduzione

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Nota: Questo modulo non è disponibile su piattaforme Windows.

Installazione

Questo modulo è disponibile soltanto se PHP è stato configurato con l'opzione --with-cyrus .

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

CYRUS_CONN_NONSYNCLITERAL (integer)
CYRUS_CONN_INITIALRESPONSE (integer)
CYRUS_CALLBACK_NUMBERED (integer)
CYRUS_CALLBACK_NOLITERAL (integer)

Sommario
cyrus_authenticate -- Autentifica attraverso un server Cyrus IMAP
cyrus_bind -- Bind callbacks ad una connessione Cyrus IMAP
cyrus_close -- Chiude la connessione con un server Cyrus IMAP
cyrus_connect -- Apre una connessione con un server Cyrus IMAP
cyrus_query -- Invia una query ad un server Cyrus IMAP
cyrus_unbind -- Unbind ...

XXII. Funzioni di Data e Ora

Introduzione

Queste funzioni ti permettono di scaricare la data e l'orario dal server dove gira il PHP. Puoi usare queste funzioni per formattare l'output delle date e degli orari in diversi modi.

Nota: Ricordati che queste funzioni dipendono dai settaggi locali del tuo server. Considera specialmente l'ora legale e gli anni bisestili.

Requisiti

Non sono necessarie librerie esterne per utilizzare questo modulo.

Installazione

Non è necessaria nessuna installazione per usare queste funzioni, esse fanno parte del core di PHP.

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

Questa estensione non definisce alcuna costante.

Sommario
checkdate -- Verifica una data/orario gragoriana/o
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_sunrise -- Returns time of sunrise for a given day and location
date_sunset -- Returns time of sunset for a given day and location
date -- Formatta una data o orario locale
getdate -- Riceve informazioni su data/orario
gettimeofday -- Riceve l'orario attuale
gmdate -- Formatta una data/ora GMT/UTC
gmmktime -- Riceve l'UNIX timestamp per una data GMT
gmstrftime -- Formatta una data/ora GMT/UTC secondo i parametri locali
idate -- Format a local time/date as integer
localtime -- Riceve l'orario locale
microtime -- Restituisce l'attuale UNIX timestamp con i microsecondi
mktime -- Restituisce la UNIX timestamp per una data
strftime -- Formatta una data/orario locale accordandola/o alle impostazioni locali according to locale settings
strptime -- Parse a time/date generated with strftime()
strtotime -- Analizza le descrizioni testuali di datetime in Inglese nell'UNIX timestamp
time -- Restituisce l'attuale UNIX timestamp

checkdate

(PHP 3, PHP 4, PHP 5)

checkdate -- Verifica una data/orario gragoriana/o

Descrizione

bool checkdate ( int mese, int giorno, int anno )

Restituisce TRUE se la data inserita è valida; altrimenti restituisce FALSE. Controlla la validità di una data formata dagli argomenti. Una data è considerata valida se:

anno è compreso tra 1 e 32767
mese è compreso tra 1 e 12
Giorno è compreso tra il numero dei giorni possibile per il mese dato. Gli anno(i) bisestili sono presi in considerazione.

Guarda anche mktime() e strtotime().

date_default_timezone_get

(PHP 5 >= 5.1.0RC1)

date_default_timezone_get -- Gets the default timezone used by all date/time functions in a script

Descrizione

string date_default_timezone_get ( void )

This functions returns the default timezone, using the following "guess" order:

The timezone set using the date_default_timezone_set() function (if any)
The TZ environment variable (if non empty)
The date.timezone ini option (if set)
"magical" guess (if the operating system supports it)
If none of the above options succeeds, return UTC

Valori restituiti

Returns a string.

Vedere anche:

date_default_timezone_set()

date_default_timezone_set

(PHP 5 >= 5.1.0RC1)

date_default_timezone_set -- Sets the default timezone used by all date/time functions in a script

Descrizione

bool date_default_timezone_set ( string timezone_identifier )

date_default_timezone_set() sets the default timezone used by all date/time functions.

Nota: Since PHP 5.1.0 (when the date/time functions were rewritten), every call to a date/time function will generate a E_NOTICE if the timezone isn't valid, and/or a E_STRICT message if using the system settings or the TZ environment variable.

Elenco dei parametri

timezone_identifier: The timezone identifier, like UTC or Europe/Lisbon. The list of valid identifiers is available in the Appendice H.

Valori restituiti

This function always returns TRUE (even if the timezone_identifier isn't valid).

Vedere anche:

date_default_timezone_get()

date_sunrise

(PHP 5)

date_sunrise -- Returns time of sunrise for a given day and location

Description

mixed date_sunrise ( int timestamp [, int format [, float latitude [, float longitude [, float zenith [, float gmt_offset]]]]] )

date_sunrise() returns the sunrise time for a given day (specified as a timestamp) and location. The latitude, longitude and zenith parameters default to the date.default_latitude, date.default_longitude and date.sunrise_zenith configuration options, respectively.

The latitude defaults to North. So, if you want to specify a South value, you must pass a negative value. The same note applies to longitude, which defaults to East.

The gmt_offset parameter is specified in hours.

Tabella 1. format constants

constant	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

Esempio 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); ?>
Il precedente esempio visualizzerà qualcosa simile a:
Mon Dec 20 2004, sunrise time : 08:54

date_sunset

(PHP 5)

date_sunset -- Returns time of sunset for a given day and location

Description

mixed date_sunset ( int timestamp [, int format [, float latitude [, float longitude [, float zenith [, float gmt_offset]]]]] )

date_sunset() returns the sunset time for a given day (specified as a timestamp) and location. The latitude, longitude and zenith parameters default to the date.default_latitude, date.default_longitude and date.sunset_zenith configuration options, respectively.

The latitude defaults to North. So, if you want to specify a South value, you must pass a negative value. The same note applies to longitude, which defaults to East.

The gmt_offset parameter is specified in hours.

Tabella 1. format constants

constant	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

Esempio 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); ?>
Il precedente esempio visualizzerà qualcosa simile a:
Mon Dec 20 2004, sunset time : 18:13

date

(PHP 3, PHP 4, PHP 5)

date -- Formatta una data o orario locale

Descrizione

string date ( string formato [, int timestamp] )

Restituisce una stringa formattata in accordo con il formato della stringa usato nell' intero timestamp o nell'attuale orario locale se timestamp non è assegnato.

Nota: Il valido intervallo del timestamp è abitualmente da Fri, 13 Dec 1901 20:45:54 GMT a Tue, 19 Jan 2038 03:14:07 GMT. (Queste date corrispondono al valore minimo e al massimo per un intero segnato a 32-bit.)
Per generare un timestamp da una stringa rappresentante la data, devi sapere usare strtotime(). In aggiunta, dei databases hanno funzioni che convertono i loro formati di data in timestamps (come la funzione di MySQL, UNIX_TIMESTAMP).

I seguenti caratteri sono utilizzati nella stringa formato:

a - "am" o "pm"
A - "AM" o "PM"
B - Swatch Internet time
d - giorno del mese, 2 cifre senza tralasciare gli zero; i.e. "01" a "31"
D - giorno della settimana, testuale, 3 lettere; i.e. "Fri"
F - mese, testuale, long; i.e. "January"
g - ora, formato a 12-ore senza eventuali zero; i.e. "1" a "12"
G - ora, formato a 24-ore senza eventuali zero; i.e. "0" a "23"
h - ora, formato a 12-ore; i.e. "01" a "12"
H - ora, formato a 24-ore; i.e. "00" a "23"
i - minuti; i.e. "00" a "59"
I (i grande) - "1" se c'è l'ora legale, "0" altrimenti.
j - giorno del mese senza eventuali zero; i.e. "1" a "31"
l ('L' piccola) - giorno della settimana, testuale, long; i.e. "Friday"
L - valore booleano per stabilire se è un anno bisestile; i.e. "0" o "1"
m - mese; i.e. "01" a "12"
M - mese, testuale, 3 lettere; i.e. "Jan"
n - mese senza eventuali zero; i.e. "1" a "12"
O - Differenza in ore dal fuso orario Greenwich; i.e. "+0200"
r - Data formattata RFC 822; i.e. "Thu, 21 Dec 2000 16:01:07 +0200" (aggiunto nel PHP 4.0.4)
s - secondi; i.e. "00" a "59"
S - Suffisso ordinale Inglese per i giorni del mese, 2 caratteri; i.e. "th", "nd"
t - numero di giorni del mese dato; i.e. "28" a "31"
T - Fuso orario di questo computer; i.e. "MDT"
U - secondi dall'epoca since the epoch
w - giorno della settimana, numerico, i.e. "0" (Domenica) a "6" (Sabato)
W - ISO-8601 Numero della settimana dell'anno, le settimane iniziano il lunedì (aggiunto in PHP 4.1.0) (Sabato)
Y - anno, 4 cifre; i.e. "1999"
y - anno, 2 cifre; i.e. "99"
z - giorno dell'anno; i.e. "0" a "365"
Z - Fuso orario in secondi (i.e. "-43200" a "43200"). Il fuso orario ad ovest dell'UTC è sempre negativo, e per quelli ad est è sempre positivo.

Caratteri non utilizzati nella stringa del formato saranno scritti come sono. Il formato "Z" restituirà sempre "0" quando si usa gmdate().

Esempio 1. Esempio di date()
echo date ("l dS of F Y h:i:s A"); echo "July 1, 2000 is on a " . date ("l", mktime(0,0,0,7,1,2000));

Puoi utilizzare un carattere utilizzabile nella stringa del formato come carattere normale facendolo semplicemente precedere dal carattere di escape, il backslash. Se il carattere con un backslash è ancora una sequenza speciale, devi inserire di nuovo il carattere di escape per il backslash.
Esempio 2. Caratteri di escape in date()
echo date("l \\t\h\e jS"); // scrive qualcosa tipo 'Saturday the 8th'

È possibile usare date() e mktime() assieme per cercare delle date nel futuro o nel passato.
Esempio 3. Esempio di date() e mktime()
$tomorrow = mktime (0,0,0,date("m") ,date("d")+1,date("Y")); $lastmonth = mktime (0,0,0,date("m")-1,date("d"), date("Y")); $nextyear = mktime (0,0,0,date("m"), date("d"), date("Y")+1);

Nota: Questo può essere più affidabile della semplice addizione e sottrazione del numero di secondi in un giorno o mese a un timestamp a causa del daylight savings time.

Alcuni esempi della formattazione di date(). Nota che puoi scrivere qualsiasi altro carattere senza escape, il quale attualmente non dovrebbe produrre risultati indesiderati, ma altri caratteri potrebbero essere assegnati come caratteri della stringa di formattazione nelle prossime versioni del PHP. Quando si utilizza il carattere di escape, assicurati di usare un singolo apice per prevenire che caratteri come \n facciano iniziare una nuova linea.
Esempio 4. Formattazione con date()
/* Today is March 10th, 2001, 5:16:18 pm */ $today = date("F j, Y, g:i a"); // March 10, 2001, 5:16 pm $today = date("m.d.y"); // 03.10.01 $today = date("j, n, Y"); // 10, 3, 2001 $today = date("Ymd"); // 20010310 $today = date('h-i-s, j-m-y, it is w Day z '); // 05-16-17, 10-03-01, 1631 1618 6 Fripm01 $today = date('\i\t \i\s \t\h\e jS \d\a\y.'); // It is the 10th day. $today = date("D M j G:i:s T Y"); // Sat Mar 10 15:16:08 MST 2001 $today = date('H:m:s \m \i\s\ \m\o\n\t\h'); // 17:03:17 m is month $today = date("H:i:s"); // 17:16:17

Per formattare le date in lingue diverse dall'inglese, dovresti usare le funzioni setlocale() e strftime().

Guarda anche getlastmod(), gmdate(), mktime(), strftime() e time().

getdate

(PHP 3, PHP 4, PHP 5)

getdate -- Riceve informazioni su data/orario

Descrizione

array getdate ( [int timestamp] )

Restituisce un array associativo contenente le informazioni sulla data del timestamp, o dell'attuale orario locale se non è stato assegnato timestamp, con i seguenti elementi di array:

"seconds" - secondi
"minutes" - minuti
"hours" - ore
"mday" - giorno del mese
"wday" - giorno della settimana, numerico : da 0 come Domenica a 6 come Sabato
"mon" - mese, numerico
"year" - anno, numerico
"yday" - giorno dell'anno, numerico; i.e. "299"
"weekday" - giorno della settimana, testuale, per intero; i.e. "Friday"
"month" - mese, testuale, per intero; i.e. "January"

Esempio 1. Esempio di getdate()

$today = getdate(); 
$month = $today['month']; 
$mday = $today['mday']; 
$year = $today['year']; 
echo "$month $mday, $year";

gettimeofday

(PHP 3 >= 3.0.7, PHP 4, PHP 5)

gettimeofday -- Riceve l'orario attuale

Descrizione

array gettimeofday ( void )

Questa è un'interfaccia di gettimeofday(2). Restituisce un array associativo contenente i dati restituiti dalla chiamata al sistema.

"sec" - secondi
"usec" - microsecondi
"minuteswest" - minuti ovest di Greenwich
"dsttime" - tipo di correzione dell'ora legale

gmdate

(PHP 3, PHP 4, PHP 5)

gmdate -- Formatta una data/ora GMT/UTC

Descrizione

string gmdate ( string formato [, int timestamp] )

Identica alla funzione date() eccetto per il fatto che l'orario restituito è del Greenwich Mean Time (GMT). Per esempio, quando si è in Finlandia (GMT +0200), la prima linea sotto scrive "Jan 01 1998 00:00:00", mentre la seconda scrive "Dec 31 1997 22:00:00".
Esempio 1. Esempio di gmdate()
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));

Guarda anche date(), mktime(), gmmktime() e strftime().

gmmktime

(PHP 3, PHP 4, PHP 5)

gmmktime -- Riceve l'UNIX timestamp per una data GMT

Descrizione

int gmmktime ( int ora, int minuto, int secondo, int mese, int giorno, int anno [, int is_dst] )

Identica alla funzione mktime() eccetto per il paramentro passato, che rappresenta una data GMT.

gmstrftime

(PHP 3 >= 3.0.12, PHP 4, PHP 5)

gmstrftime -- Formatta una data/ora GMT/UTC secondo i parametri locali

Descrizione

string gmstrftime ( string formato [, int timestamp] )

Si comporta allo stesso modo della funzione strftime() eccetto che l'orario restituito è del Greenwich Mean Time (GMT). Ad esempio, quando si è nell' Eastern Standard Time (GMT -0500), la prima linea sotto scrive "Dec 31 1998 20:00:00", mentre la seconda scrive "Jan 01 1999 01:00:00".
Esempio 1. Esempio di gmstrftime()
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";

Guarda anche strftime().

idate

(PHP 5)

idate -- Format a local time/date as integer

Description

int idate ( string format [, int timestamp] )

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.

Tabella 1. The following characters are recognized in the format parameter string

`format` character	Description
`B`	Swatch Beat/Internet Time
`d`	Day of the month
`h`	Hour (12 hour format)
`H`	Hour (24 hour format)
`i`	Minutes
`I`	returns `1` if DST is activated, `0` otherwise
`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 GMT - 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

Nota: As idate() returns always an integer and as they can't start with a "0", idate() may return less digits then you would expect. See the example below:

<?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 -- Riceve l'orario locale

Descrizione

array localtime ( [int timestamp [, bool is_associative]] )

La funzione localtime() restituisce un array identico a quello della struttura della chimata della funzione di C. Il primo argomento per localtime() è il timestamp, se non esiste viene assegnato di default l'orario attuale. Il secondo argomento di localtime() è is_associative, se questo è settato a 0 o non sostituito l'array restituirà un regolare array numerico indicizzato. Se l'argomento è settato a 1, localtime() è un array associativo contenente tutti gli elementi differenti della struttura restituita dalla funzione chiamata localtime di C. Il nome delle differenti chiavi dell'array associativo sono le seguenti:

"tm_sec" - secondi
"tm_min" - minuti
"tm_hour" - ora
"tm_mday" - giorno del mese
"tm_mon" - mese dell'anno, iniziando con 0 per Gennaio
"tm_year" - Anni dal 1900
"tm_wday" - Giorno della settimana
"tm_yday" - Giorno dell'anno
"tm_isdst" - Se l'ora legale è effettiva

microtime

(PHP 3, PHP 4, PHP 5)

microtime -- Restituisce l'attuale UNIX timestamp con i microsecondi

Descrizione

string microtime ( void )

Restituisce la stringa "msec sec" dove sec è l'attuale orario misurato nel numero di secondi dalla Unix Epoch (0:00:00 January 1, 1970 GMT), e msec è la parte in microsecondi. Questa funzione è disponibile solo su sistemi operativi che supportano la chiamata di sistema gettimeofday().

Entrambi le parti della stringa sono restituite in unità di secondi.
Esempio 1. Esempio di microtime()
function getmicrotime(){ list($usec, $sec) = explode(" ",microtime()); return ((float)$usec + (float)$sec); } $time_start = getmicrotime(); for ($i=0; $i < 1000; $i++){ //do nothing, 1000 times } $time_end = getmicrotime(); $time = $time_end - $time_start; echo "Did nothing in $time seconds";

Vedere anche time().

mktime

(PHP 3, PHP 4, PHP 5)

mktime -- Restituisce la UNIX timestamp per una data

Descrizione

int mktime ( int hour, int minute, int second, int month, int day, int year [, int is_dst] )

Attenzione: Nota lo strano ordine degli argomenti, che differiscono dal normale ordine degli argomenti in una normale chiamata UNIX mktime() e che non si presta bene a far comparire i parametri da destra a sinistra (guarda sotto). E' un comune errore la confusione di questi argomenti in uno script.

Restituisce la Unix timestamp corrispondente all'argomento dato. Questa timestamp è un intero lungo contenente il numero di secondi tra la Unix Epoch (January 1 1970) e la data e orario specificati.

Gli argomenti possono essere omessi nell'ordine da destra a sinistra; degli argomenti omessi saranno impostati con l'attuale valore accordandolo alla data e orario locale.

is_dst può essere impostato su 1 se l'orario è nell'ora legale, 0 altrimenti, o -1 (di default) se è sconosciuta la presenza dell'ora legale o meno. Se è sconosciuto, il PHP proverà ad impostarlo da se. Questo può causare un risultato non aspettato (ma non sbagliato).

Nota: is_dst è stato aggiunto nella verisone 3.0.10.

mktime() è usata per fare calcoli tra date e validazioni, come può calcolare automaticamente il corretto valore per un valore fuori dall'intervallo valido. Per esempio, ognuna delle seguenti linee produce la stringa "Jan-01-1998".
Esempio 1. Esempio di mktime()
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));
Year può avere sia 2 che 4 cifre, con valori compresi tra 0-69 e 2000-2069 oppure tra 70-99 e 1970-1999 (sui sistemi dove time_t è un intero segnato a 32bit, come sulla maggior parte dei PC di oggi, l'intervallo valido per year è tra 1902 e 2037).

L'ultimo giorno del mese dato può essere espresso come il giorno "0" del mese successivo, non come il giorno -1. Entrami i seguenti esempi produrranno la stringa "L'ultimo giorno di Feb 2000 è: 29".
Esempio 2. L'ultimo giorno del mese successivo
$lastday = mktime (0,0,0,3,0,2000); echo strftime ("L'ultimo giorno di Feb 2000 è: %d", $lastday); $lastday = mktime (0,0,0,4,-31,2000); echo strftime ("L'ultimo giorno di Feb 2000 è: %d", $lastday);

Date con anno, mese e giorno uguali a 0 non sono considerate valide (altrimenti saranno considerate come 30.11.1999, quando hanno uno strano behavior).

Guarda anche date() e time().

strftime

(PHP 3, PHP 4, PHP 5)

strftime -- Formatta una data/orario locale accordandola/o alle impostazioni locali according to locale settings

Descrizione

string strftime ( string format [, int timestamp] )

Restituisce una stringa formattata in accordo con la stringa del formato data usando il parametro dato timestamp o l'attuale orario locale se non è stato dato il timestamp. I nomi di mesi e giorni della settimana e le altre stringhe dipendenti dalla lingua rispettano le attuali impostazioni locali con setlocale().

Le seguenti sequenze di caratteri sono utilizzate nella stringa del formato:

%a - Nome del giorno della settimana abbreviato in accordo con i parametri locali
%A - Nome completo del giorno della settimana in accordo con i parametri locali
%b - Nome del mese abbreviato in accordo con i parametri locali
%B - Nome completo del mese in accordo con i parametri locali
%c - Rappresentazione preferita di data e orario per le attuali impostazioni locali
%C - numero del secolo (l'anno diviso 100 e troncato in un intero, intervallo tra 00 e 99)
%d - giorno del mese come numero decimale (intervallo tra 01 e 31)
%D - come %m/%d/%y
%e - giorno del mese come numero decimale, un singolo carattere è preceduto da uno spapzio (intervallo tra ' 1' e '31')
%g - come %G, ma senza il secolo.
%G - L'anno a 4 cifre corrispondente al numero di setitmana ISO (vedi %V). Questa ha lo stesso formato e valore di %Y, eccetto che se il numero di settimana ISO appartiene al precedente o prossimo anno, è invece utilizzato l'anno attuale.
%h - come %b
%H - ora come numero decimale usando il sistema a 24 ore (intervallo tra 00 e 23)
%I - ora come numero decimale usando il sistema a 12 ore (intervallo tra 01 e 12)
%j - giorno dell'anno come numero decimale (intervallo tra 001 e 366)
%m - mese come numero decimale (intervallo tra 01 e 12)
%M - minuto come numero decimale
%n - carattere di nuova linea
%p - entrambi `am' o `pm' accordati a un valore di tempo dato, o alle stringhe corrispondenti per le impostazioni locali
%r - orario in notazione a.m. e p.m
%R - orario nella notazione a 24 ore
%S - secondi come numero decimale
%t - Carattere di tabella
%T - orario attuale, identico a %H:%M:%S

%u - giorno della settimana come numero decimale [1,7], dove 1 rappresenta il Lunedì

Avvertimento

Sun Solaris sembra far iniziare con la Domenica a come 1 sebbe la ISO 9889:1999 (l'attuale standard di C) specifica chiaramente che dovrebbe iniziare dal Lunedì.

%U - numero della settimana dell'anno in corso come numero decimale, iniziando dalla prima Domenica come primo giorno della prima settimana
%V - Il numero di settimana ISO 8601:1988 dell'anno attuale come numero decimale, intervallo tra 01 e 53, dove la settimana 1 è la prima settimana che ha almeno 4 giorni dell'attuale anno, e con il Lunedì come primo giorno della settimana. (Utilizza %G o %g per l'anno componente che corrisponde al numero di settimana per il timestamp specificato.)
%W - numero della settimana dell'attuale anno come numero decimale, partendo con il primo Lunedì come primo giorno della prima settimana
%w - giorno della settimana come decimale, dove la Domenica è 0
%x - visualizzazione della data preferita dalle impostazioni del sistema locale senza orario
%X - visualizzazione dell'orario preferito dalle impostazioni del sistema locale senza data
%y - anno come numero decimale senza secolo (intervallo tra 00 e 99)
%Y - anno come numero decimale incluso il secolo
%Z - fuso orario o abbreviazione
%% - il carattere `%'

Nota: Non tutte le sequenze di caratteri potrebbero essere supportate dalla tua libreria locale di C, in tal caso la funzione strftime() non sarà supportata dal PHP. Questo significa che %T e %D non funzioneranno sotto Windows.

Esempio 1. Esempio di strftime()

setlocale (LC_TIME, "C");
print (strftime ("%A in Finlandese è "));
setlocale (LC_TIME, "fi_FI");
print (strftime ("%A, in Francese "));
setlocale (LC_TIME, "fr_FR");
print (strftime ("%A e in Italiano "));
setlocale (LC_TIME, "it_IT");
print (strftime ("%A.\n"));

Questo esempio funziona se hai le ripettive impostazioni di lingua installate nel tuo sistema.

Guarda anche setlocale() e mktime() e le specifiche dell' Open Group per strftime().

strptime

(PHP 5 >= 5.1.0RC1)

strptime -- Parse a time/date generated with strftime()

Description

array strptime ( string 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).

Nota: Questa funzione non è implementata su piattaforme Windows

Elenco dei parametri

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()).

For more information about the format options, read the strftime() page.

Valori restituiti

Returns an array, or FALSE on failure.

Tabella 1. The following parameters are returned in the array

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`

Esempi

Esempio 1. strptime() example
<?php $format = '%d/%m/%Y %H:%M:%S'; $strf = strftime($format); echo "$strf\n"; print_r(strptime($strf, $format)); ?>
Il precedente esempio visualizzerà qualcosa simile a:
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] => )

Vedere anche:

strftime()

strtotime

(PHP 3 >= 3.0.12, PHP 4, PHP 5)

strtotime -- Analizza le descrizioni testuali di datetime in Inglese nell'UNIX timestamp

Descrizione

int strtotime ( string time [, int now] )

La funzione aspetta di avere una stringa contenente un formato di data in Inglese e proverà a passare questo formato all'UNIX timestamp relativo al timestamp dato in now, o l'attuale orario se non è stato passato il parametro. Sul fallimento, è restituito -1.

Perché strtotime() si comporti in accordo con la sintassi della data GNU, dai uno sguardo alla pagina del manuale GNU intitolata Date Input Formats. Descrive se c'è una sinstassi valida per il parametro time.

Esempio 1. strtotime() - esempi
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";

Esempio 2. Controllo per il fallimento
$str = 'Not Good'; if (($timestamp = strtotime($str)) === -1) { echo "The string ($str) is bogus"; } else { echo "$str == ". date('l dS of F Y h:i:s A',$timestamp); }

Nota: L'intervallo valido di un timestamp è normalmente da Fri, 13 Dec 1901 20:45:54 GMT a Tue, 19 Jan 2038 03:14:07 GMT. (Queste sono le date ce corrispondono al minimo e al massimo valore per un intero segnato a 32 bit.)

time

(PHP 3, PHP 4, PHP 5)

time -- Restituisce l'attuale UNIX timestamp

Descrizione

int time ( void )

Restituisce l'attuale data e orario misurata in numero di secondi dalla Unix Epoch (January 1 1970 00:00:00 GMT).

Guarda anche date().

XXIII. DB++ Functions

Avvertimento

Introduzione

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 a SQL database in the first place but provides its own AQL query language which is much more influenced by the relational algebra then 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.

Requisiti

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).

Installazione

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.

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Tipi di risorse

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.

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

db++ error codes

Tabella 1. 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

Sommario
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

dbplus_add

(4.1.0 - 4.2.3 only, PECL)

dbplus_add -- Add a tuple to a relation

Description

int dbplus_add ( resource relation, array tuple )

Avvertimento

This function will add a tuple to a relation. The tuple data is an array of attribute/value pairs to be inserted into the given relation. After successful execution the tuple array will contain the complete data of the newly created tuple, including all implicitly set domain fields like sequences.

The function will return zero (aka. DBPLUS_ERR_NOERR) on success or a db++ error code on failure. See dbplus_errcode() or the introduction to this chapter for more information on db++ error codes.

dbplus_aql

(4.1.0 - 4.2.3 only, PECL)

dbplus_aql -- Perform AQL query

Description

resource dbplus_aql ( string query [, string server [, string dbpath]] )

Avvertimento

dbplus_aql() will execute an AQL query on the given server and dbpath.

On success it will return a relation handle. The result data may be fetched from this relation by calling dbplus_next() and dbplus_current(). Other relation access functions will not work on a result relation.

Further information on the AQL A... Query Language is provided in the original db++ manual.

dbplus_chdir

(4.1.0 - 4.2.3 only, PECL)

dbplus_chdir -- Get/Set database virtual current directory

Description

string dbplus_chdir ( [string newdir] )

Avvertimento

dbplus_chdir() will change the virtual current directory where relation files will be looked for by dbplus_open(). dbplus_chdir() will return the absolute path of the current directory. Calling dbplus_chdir() without giving any newdir may be used to query the current working directory.

dbplus_close

(4.1.0 - 4.2.3 only, PECL)

dbplus_close -- Close a relation

Description

mixed dbplus_close ( resource relation )

resource dbplus_open ( string name )

string dbplus_tcl ( int sid, string script )

int dbplus_xunlockrel ( resource relation )

Avvertimento

dbplus_xunlockrel() will release an exclusive lock on relation previously obtained by dbplus_xlockrel().

XXIV. Database (dbm-style) Abstraction Layer Functions

Introduzione

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 Sleepycat Software's DB2. (This is not to be confused with IBM's DB2 software, which is supported through the ODBC functions.)

Requisiti

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.

Tabella 1. List of 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 Sleepycat Software's DB2. 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 Sleepycat Software's DB3.
`db4`	DB4 is Sleepycat Software's DB4. This is available since PHP 4.3.2.
`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://qdbm.sourceforge.net.

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().

Installazione

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.

Avvertimento

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 malfaunctioning single handlers but not combinations.

Tabella 2. Supported DBA handlers

Handler	Configure Switch
`dbm`	To enable support for dbm add `--with-dbm[=DIR]`. Nota: dbm normally is a wrapper which often results in failures. This means you should only use dbm if you are sure it works and if you really need this format.
`ndbm`	To enable support for ndbm add `--with-ndbm[=DIR]`. Nota: ndbm normally is a wrapper which often results in failures. This means you should only use ndbm if you are sure it works and if you really need this format.
`gdbm`	To enable support for gdbm add `--with-gdbm[=DIR]`.
`db2`	To enable support for db2 add `--with-db2[=DIR]`. Nota: db2 conflicts with db3 and db4.
`db3`	To enable support for db3 add `--with-db3[=DIR]`. Nota: db3 conflicts with db2 and db4.
`db4`	To enable support for db4 add `--with-db4[=DIR]`. Nota: db4 conflicts with db2 and db3. Nota: This was added in PHP 4.3.2. In earlier versions of PHP you need to use `--with-db3=DIR` with DIR being the path to db4 library. It is not possible to use db versions starting from 4.1 with PHP prior to version 4.3.0. Also, the db libraries with versions 4.1 through 4.1.24 cannot be used in any PHP version.
`cdb`	To enable support for cdb add `--with-cdb[=DIR]`. Nota: Since PHP 4.3.0 you can omit DIR to use the bundled cdb library that adds the cdb_make handler which allows creation of cdb files and allows to access cdb files on the network using PHP's streams.
`flatfile`	To enable support for flatfile add `--with-flatfile`. Nota: This was added in PHP 4.3.0 to add compatibility with deprecated dbm extension. Use this handler only when you cannot install one of the libraries required by the other handlers and when you cannot use bundled cdb handler.
`inifile`	To enable support for inifile add `--with-inifile`. Nota: This was added in PHP 5.0.0 and allows to read and set microsoft style `.ini` files (like the `php.ini` file).
`qdbm`	To enable support for qdbm add `--with-qdbm[=DIR]`. Nota: qdbm conflicts with dbm and gdbm. Nota: This was added in PHP 5.0.0. The qdbm library can be loaded from http://qdbm.sourceforge.net.

Nota: 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.

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Tipi di risorse

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.

Costanti predefinite

Questa estensione non definisce alcuna costante.

Esempi

Esempio 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.

Esempio 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); } ?>

Sommario
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

dba_close

(PHP 3 >= 3.0.8, PHP 4, PHP 5)

dba_close -- Close a DBA database

Descrizione

void dba_close ( resource handle )

dba_close() closes the established database and frees all resources of the specified database handle.

Elenco dei parametri

handle: The database handler, returned by dba_open() or dba_popen().

Valori restituiti

No value is returned.

Vedere anche:

dba_open()

dba_popen()

dba_delete

(PHP 3 >= 3.0.8, PHP 4, PHP 5)

dba_delete -- Delete DBA entry specified by key

Descrizione

bool dba_delete ( string key, resource handle )

dba_delete() deletes the specified entry from the database.

Elenco dei parametri

key: The key of the entry which is deleted.
handle: The database handler, returned by dba_open() or dba_popen().

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

dba_exists

(PHP 3 >= 3.0.8, PHP 4, PHP 5)

dba_exists -- Check whether key exists

Descrizione

bool dba_exists ( string key, resource handle )

dba_exists() checks whether the specified key exists in the database.

Elenco dei parametri

key: The key the check is performed for.
handle: The database handler, returned by dba_open() or dba_popen().

Valori restituiti

Returns TRUE if the key exists, FALSE otherwise.

Vedere anche:

dba_fetch

(PHP 3 >= 3.0.8, PHP 4, PHP 5)

dba_fetch -- Fetch data specified by key

Descrizione

string dba_fetch ( string key, resource handle )

string dba_fetch ( string key, int skip, resource handle )

dba_fetch() fetches the data specified by key from the database specified with handle.

Elenco dei parametri

key: The key the data is specified by.
Nota: 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().

Valori restituiti

Returns the associated string if the key/data pair is found, FALSE otherwise.

Log delle modifiche

Versione	Descrizione
4.3	The `skip` parameter is available to support cdb's capability of multiple keys having the same name.

Vedere anche:

dba_key_split()

dba_firstkey

(PHP 3 >= 3.0.8, PHP 4, PHP 5)

dba_firstkey -- Fetch first key

Descrizione

string dba_firstkey ( resource 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.

Elenco dei parametri

handle: The database handler, returned by dba_open() or dba_popen().

Valori restituiti

Returns the key on success, or FALSE on failure.

Vedere anche:

dba_nextkey()

dba_key_split()

Example 2 in the DBA examples

dba_handlers

(PHP 4 >= 4.3.0, PHP 5)

dba_handlers -- List all the handlers available

Descrizione

array dba_handlers ( [bool full_info] )

dba_handlers() list all the handlers supported by this extension.

Elenco dei parametri

full_info: Turns on/off full information display in the result. The default is FALSE.

Valori restituiti

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.

Nota: When the internal cdb library is used you will see cdb and cdb_make.

Esempi

Esempio 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"; } ?>
Il precedente esempio visualizzerà qualcosa simile a:
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 3 >= 3.0.8, PHP 4, PHP 5)

dba_insert -- Insert entry

Descrizione

bool dba_insert ( string key, string value, resource handle )

dba_insert() inserts the entry described with key and value into the database.

Elenco dei parametri

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().

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

dba_key_split

(PHP 5)

dba_key_split -- Splits a key in string representation into array representation

Descrizione

mixed dba_key_split ( mixed key )

dba_key_split() splits a key (string representation) into an array representation.

Elenco dei parametri

key: The key in string representation.

Valori restituiti

Returns an array of the form array(0 => group, 1 => value_name). This function will return FALSE if key is NULL or FALSE.

Vedere anche:

dba_firstkey()

dba_nextkey()

dba_list

(PHP 4 >= 4.3.0, PHP 5)

dba_list -- List all open database files

Descrizione

array dba_list ( void )

dba_list() list all open database files.

Valori restituiti

An associative array, in the form resourceid => filename.

dba_nextkey

(PHP 3 >= 3.0.8, PHP 4, PHP 5)

dba_nextkey -- Fetch next key

Descrizione

string dba_nextkey ( resource handle )

dba_nextkey() returns the next key of the database and advances the internal key pointer.

Elenco dei parametri

handle: The database handler, returned by dba_open() or dba_popen().

Valori restituiti

Returns the key on success, or FALSE on failure.

Vedere anche:

dba_firstkey()

dba_key_split()

Example 2 in the DBA examples

dba_open

(PHP 3 >= 3.0.8, PHP 4, PHP 5)

dba_open -- Open database

Descrizione

resource dba_open ( string path, string mode [, string handler [, mixed ...]] )

dba_open() establishes a database instance for path with mode using handler.

Elenco dei parametri

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.

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.

Nota: There can only be one writer for one database file. When you use dba on a webserver 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:
Tabella 1. 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 mode parameter.

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.

Valori restituiti

Returns a positive handle on success, or FALSE on failure.

Log delle modifiche

Versione	Descrizione
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).

Vedere anche:

dba_popen()

dba_close()

dba_optimize

(PHP 3 >= 3.0.8, PHP 4, PHP 5)

dba_optimize -- Optimize database

Descrizione

bool dba_optimize ( resource handle )

dba_optimize() optimizes the underlying database.

Elenco dei parametri

handle: The database handler, returned by dba_open() or dba_popen().

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

dba_sync()

dba_popen

(PHP 3 >= 3.0.8, PHP 4, PHP 5)

dba_popen -- Open database persistently

Descrizione

resource dba_popen ( string path, string mode [, string handler [, mixed ...]] )

dba_popen() establishes a persistent database instance for path with mode using handler.

Elenco dei parametri

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.

Valori restituiti

Returns a positive handle on success, or FALSE on failure.

Vedere anche:

dba_open()

dba_close()

dba_replace

(PHP 3 >= 3.0.8, PHP 4, PHP 5)

dba_replace -- Replace or insert entry

Descrizione

bool dba_replace ( string key, string value, resource handle )

dba_replace() replaces or inserts the entry described with key and value into the database specified by handle.

Elenco dei parametri

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().

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

dba_sync

(PHP 3 >= 3.0.8, PHP 4, PHP 5)

dba_sync -- Synchronize database

Descrizione

bool dba_sync ( resource handle )

dba_sync() synchronizes the database. This will probably trigger a physical write to the disk, if supported.

Elenco dei parametri

handle: The database handler, returned by dba_open() or dba_popen().

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

dba_optimize()

XXV. Funzioni dBase

Introduzione

Queste funzioni consentono di accedere ai record memorizzati nei database in formato dBase (dbf).

Non è previsto il supporto per indici o campi memo. Manca anche il supporto per il locking. E' probabile che due processi concorrenti che modifichino lo stesso database, finiscano con il rovinare il Database.

I files dBase sono semplici files sequenziali o records a lunghezza fissa. I record sono aggiunti (append) alla fine del file e quelli cancellati sono conservati fino alla chiamata della funzione dbase_pack().

Si raccomanda di non usare i files dBase come database di lavoro. Scegliere piuttosto qualsiasi reale SQL server; MySQL o Postgres sono scelte comuni con PHP. Il supporto dBase è presente per permettervi di importare ed esportare dati da e verso il vostro web database, perchè il formato del file è comunemente ben interpretato dai fogli elettronici e dagli organizers di Windows.

Installazione

Allo scopo di abilitare le librerie dbase fornite e di usare queste funzioni, si deve compilare PHP con l'opzione --enable-dbase .

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Costanti predefinite

Questa estensione non definisce alcuna costante.

Sommario
dbase_add_record -- Aggiunge un record ad un database dBase
dbase_close -- Chiude un database dBase
dbase_create -- Crea un database dBase
dbase_delete_record -- Cancella un record da un database dBase
dbase_get_header_info -- Ottenere le informazioni di intestazione di un database dBase
dbase_get_record_with_names -- Estrae un record da un database dBase come un array associativo
dbase_get_record -- Estrae un record da un database dBase
dbase_numfields -- Restituisce il numero di campi in un database dBase.
dbase_numrecords -- Restituisce il numero di records in un database dBase.
dbase_open -- Apre un database dBase
dbase_pack -- Stabilizza un database dBase
dbase_replace_record -- Sostituisce un record in un database dBase

Il parametro fields è un array di arrays, ciascun array descrive il formato di un campo nel database. Ogni campo consiste di un nome, un carattere che indica il tipo di campo, una lunghezza, e una precisione.

I tipi di campo disponibili sono:

L: Boolean. Questi non hanno una lunghezza o una precisione.
M: Memo. (Nota che non sono supportati da PHP.) Questi non hanno una lunghezza o una precisione.
D: Date (memorizzate nel formato YYYYMMDD). Questi non hanno una lunghezza o una precisione.
N: Number. Questi hanno sia una lunghezza sia una precisione (il numero di decimali).
C: String.

Se il database è creato con successo, viene restituito un dbase_identifier, altrimenti viene restituito FALSE.
Esempio 1. Creare un file di database dBase
<?php // "database" name $dbname = "/tmp/test.dbf"; // 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($dbname, $def)) echo "<strong>Error!</strong>"; ?>

dbase_delete_record

array dbase_get_record_with_names ( int dbase_identifier, int record )

Restituisce i dati da record in un array associativo. L'array include anche un membro associativo chiamato 'deleted' che è settato a 1 se il record è stato marcato per la cancellazione (vedere dbase_delete_record()).

Ogni campo è convertito all'appropriato tipo PHP, Fanno eccezione:

Le date, che sono lasciate come stringhe.
Gli interi che avrebbero causato un overflow (> 32 bits) sono restituiti come stringhe.

dbase_get_record

(PHP 3, PHP 4, PHP 5)

dbase_get_record -- Estrae un record da un database dBase

Descrizione

array dbase_get_record ( int dbase_identifier, int record )

Restituisce i dati da record in un array. L'array è indicizzato partendo da 0, e include un membro associativo chiamato 'deleted' che è settato a 1 se il record è stato marcato per la cancellazione (vedere dbase_delete_record()).

Ogni campo è convertito all'appropriato tipo PHP, Fanno eccezione:

Le date, che sono lasciate come stringhe.
Gli interi che avrebbero causato un overflow (> 32 bits) sono restituiti come stringhe.

I parametri flags corrispondono a quelli della system call open() (Tipicamente, "0" significa sola-lettura, "1" significa sola scrittura e "2" lettura-scrittura).

Nota: Quando safe-mode è abilitato, PHP controlla che i file o le directory sulle quali si sta andando a lavorare, abbiano lo stesso UID dello script che è in esecuzione.

dbase_pack

(PHP 3, PHP 4, PHP 5)

dbase_pack -- Stabilizza un database dBase

Descrizione

bool dbase_pack ( int dbase_identifier )

Stabilizza il database specificato (cancellando permanentemente tutti i records marcati per la cancellazione usando dbase_delete_record()).

dbase_replace_record

(PHP 3 >= 3.0.11, PHP 4, PHP 5)

dbase_replace_record -- Sostituisce un record in un database dBase

Descrizione

bool dbase_replace_record ( int dbase_identifier, array record, int dbase_record_number )

Sostituisce i dati associati con il record record_number con i dati nel record nel database. Se il numero di items nel record non è uguale al numero di campi nel database, l'operazione fallirà e sarà restituito FALSE.

dbase_record_number è un integer che va da 1 al numero di records nel database (come restituito da dbase_numrecords()).

XXVI. Funzioni DBM

Introduzione

Questa funzioni consentono lo storage di records memorizzati in un dbm-style database. Questo tipo di database (supportato da Berkeley DB, GDBM, e qualche libreria di sistema, così come una built-in flatfile library) memorizza coppie key/value (al contrario dei full-blown records supportati dai database relazionali).

Nota: Il supporto per dbm è deprecato e si incoraggia ad utilizzare Database (dbm-style) abstraction layer functions.

Requisiti

Per utilizzare queste funzioni occorre compilare il PHP con il supporto per un database sottostante. Vedere l'elenco dei database supoprtati.

Installazione

Per potere utilizzare queste funzioni occorre compilare il PHP con il supporto dbm utilizzando l'opzione --with-db. Inoltre occorre garantire il supporto per il sottostante database oppure occorre utilizzare qualche libreria di sistema.

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Tipi di risorse

La funzione dbmopen() restituisce un identificatore di database che può essere utilizzato con le altre funzioni dbm.

Costanti predefinite

Questa estensione non definisce alcuna costante.

Esempi

Esempio 1. Esempio DBM
<?php $dbm = dbmopen ("lastseen", "w"); if (dbmexists ($dbm, $userid)) { $last_seen = dbmfetch ($dbm, $userid); } else { dbminsert ($dbm, $userid, time()); } do_stuff(); dbmreplace($dbm, $userid, time()); dbmclose($dbm); ?>

Sommario
dblist -- Descrive la libreria DBM-compatibile in uso.
dbmclose -- Chiude un database dbm
dbmdelete -- Cancella il valore per una chiave da un database DBM
dbmexists -- Dice se esiste un valore per una chiave in un database DBM
dbmfetch -- Estrae un valore per una chiave da un database DBM
dbmfirstkey -- Recupera la prima chiave da un database DBM
dbminsert -- Inserisce un valore per una chiave in un database DBM
dbmnextkey -- Recupera la chiave successiva da un database DBM
dbmopen -- Apre un database DBM
dbmreplace -- Sostituisce il valore per una chiave in un database DBM

Aggiunge il valore al database con la chiave specificata.

Restituisce -1 se il database è stato aperto in modalità read-only (sola lettura), 0 se l'inserimento è andato a buon fine, e 1 se la chiave specificata già esiste. (Per sostituire il valore, usa dbmreplace().)

dbmnextkey

int dbmreplace ( resource dbm_identifier, string key, string value )

Sostituisce il valore per la chiave specificata nel database.

Aggiungerà inoltre la chiave al database se la stessa non esisteva già.

XXVII. dbx Functions

Introduzione

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.

Nota: Questo modulo è stato spostato nel repository PECL e non sarà più rilascio con il PHP dalla versione 5.1.0.

Requisiti

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/.

Installazione

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.

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

Tabella 1. DBX Configuration Options

Name	Default	Changeable	Changelog
dbx.colnames_case	"unchanged"	PHP_INI_SYSTEM	Available since PHP 4.3.0.

Per maggiori dettagli sulle costanti PHP_INI_* vedere Appendice G.

Breve descrizione dei parametri di configurazione.

dbx.colnames_case string: Columns names can be returned "unchanged" or converted to "uppercase" or "lowercase". This directive can be overridden with a flag to dbx_query().

Tipi di risorse

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.

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

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)

Sommario
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 (not just in the connection)
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

dbx_close

(PHP 4 >= 4.0.6, PHP 5 <= 5.0.4)

dbx_close -- Close an open connection/database

Description

bool dbx_close ( object link_identifier )

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempio 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);
?>

Nota: Always refer to the module-specific documentation as well.

dbx_compare

(PHP 4 >= 4.1.0, PHP 5 <= 5.0.4)

dbx_compare -- Compare two rows for sorting purposes

Description

int dbx_compare ( array row_a, array row_b, string column_key [, int flags] )

dbx_compare() 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. dbx_compare() is a helper function for dbx_sort() to ease the make and use of the custom sorting function.

The flags can be set to specify comparison direction:

DBX_CMP_ASC - ascending order
DBX_CMP_DESC - descending order

and the preferred comparison type:

DBX_CMP_NATIVE - no type conversion
DBX_CMP_TEXT - compare items as strings
DBX_CMP_NUMBER - compare items numerically

One of the direction and one of the type constant can be combined with bitwise OR operator (|). The default value for the flags parameter is DBX_CMP_ASC | DBX_CMP_NATIVE.

Esempio 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.4)

dbx_connect -- Open a connection/database

Description

object dbx_connect ( mixed module, string host, string database, string username, string password [, int persistent] )

dbx_connect() 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 persistent parameter can be set to DBX_PERSISTENT, if so, a persistent connection will be created.

The module parameter 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_MYSQL or "mysql"
DBX_ODBC or "odbc"
DBX_PGSQL or "pgsql"
DBX_MSSQL or "mssql"
DBX_FBSQL or "fbsql" (available from PHP 4.1.0)
DBX_SYBASECT or "sybase_ct" (available from PHP 4.2.0)
DBX_OCI8 or "oci8" (available from PHP 4.3.0)
DBX_SQLITE or "sqlite" (PHP 5)

The host, database, username and password parameters are expected, but not always used depending on the connect functions for the abstracted module.

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.

Esempio 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); ?>

Nota: Always refer to the module-specific documentation as well.

dbx_error

(PHP 4 >= 4.0.6, PHP 5 <= 5.0.4)

dbx_error -- Report the error message of the latest function call in the module (not just in the connection)

Description

string dbx_error ( object link_identifier )

dbx_error() 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.

Esempio 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);
?>

Nota: 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.4)

dbx_escape_string -- Escape a string so it can safely be used in an sql-statement

Description

string dbx_escape_string ( object link_identifier, string text )

dbx_escape_string() returns the text, escaped where necessary (such as quotes, backslashes etc). It returns NULL on error.

Esempio 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.4)

dbx_fetch_row -- Fetches rows from a query-result that had the DBX_RESULT_UNBUFFERED flag set

Description

mixed dbx_fetch_row ( object result_identifier )

dbx_fetch_row() returns a row on success, and 0 on failure (e.g. when no more rows are available). 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().

Esempio 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";
?>

The result_identifier parameter is the result object returned by a call to dbx_query().

The returned object 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_guery were set that way.

dbx_query

(PHP 4 >= 4.0.6, PHP 5 <= 5.0.4)

dbx_query -- Send a query and fetch all results (if any)

Description

mixed dbx_query ( object link_identifier, string sql_statement [, int flags] )

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).

Esempio 1. 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);
?>

The flags parameter 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_ASSOC is also specified, the returning object contains the information related to DBX_RESULT_INFO too, 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 (PHP 5)

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 (available from PHP 4.3.0)

The case of the returned column names will not be changed.

DBX_COLNAMES_UPPERCASE (available from PHP 4.3.0)

The case of the returned column names will be changed to uppercase.

DBX_COLNAMES_LOWERCASE (available from PHP 4.3.0)

The case of the returned column names will be changed to lowercase.

Note that DBX_RESULT_INDEX is always used, regardless of the actual value of flags parameter. 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, if flags is not specified.

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_INFO or DBX_RESULT_ASSOC is specified in the flags parameter. It is a 2 dimensional array, that has two named rows (name and type) to retrieve column information.

Esempio 2. 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. If DBX_RESULT_ASSOC is set, it is possible to use $result->data[2]["field_name"].

Esempio 3. 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";
?>

Esempio 4. 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";

?>

Nota: Always refer to the module-specific documentation as well.
Column names for queries on an Oracle database are returned in lowercase.

dbx_sort

(PHP 4 >= 4.0.6, PHP 5 <= 5.0.4)

dbx_sort -- Sort a result from a dbx_query by a custom sort function

Description

bool dbx_sort ( object result, string user_compare_function )

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Nota: It is always better to use ORDER BY SQL clause instead of dbx_sort(), if possible.

Esempio 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);
?>

XXVIII. Funzioni per l'IO diretto

Introduzione

Il PHP supporta funzioni per l'I/O diretto, come descritto dallo standard POSIX (Sezione 6), per potere eseguire operazioni di I/O ad un livello inferiore rispetto agli streams del linguaggio C (fopen(), fread(),..). Si dovrebbe prendere in considerazione l'uso delle funzioni di DIO soltanto nei casi in cui occorra un controllo diretto del device. In tutti gli altri casi le funzioni filesystem sono più che adeguate.

Nota: Questo modulo è stato spostato nel repository PECL e non sarà più rilascio con il PHP dalla versione 5.1.0.

Questo modulo è disponibile sulla piattaforma Windows solo dal PHP 5.0.0

Requisiti

Non sono necessarie librerie esterne per utilizzare questo modulo.

Installazione

Per potere utilizzare queste funzioni, occorre configurare PHP con --enable-dio.

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

c (integer)
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)

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Tipi di risorse

Questa estensione definisce un solo tipo di risorsa: un descrittore di file restituito dalla funzione dio_open().

Sommario
dio_close -- Chiude il descrittore di file passato
dio_fcntl -- Esegue la funzione C fcntl su un descrittore di file
dio_open -- Apre un nuovo file nella modalità specificata da flags e i permessi indicati in mode
dio_read -- Legge n bytes da un descrittore di file
dio_seek -- Si posiziona al byte pos del file indicato da fd
dio_stat -- Restituisce le informazioni relative al file indicato da fd
dio_tcsetattr -- Imposta gli attributi terminale e la velocità per una porta seriale
dio_truncate -- Tronca il file indicato da fd ad un numero di byte specificato
dio_write -- Scrive dati sul file indicato da fd con la possibilità di troncarne la lunghezza

dio_close

(PHP 4 >= 4.2.0, PHP 5 <= 5.0.4)

dio_close -- Chiude il descrittore di file passato

Descrizione

void dio_close ( resource fd )

La funzione dio_close() chiude il descrittore di file fd.

Elenco dei parametri

fd: Il descrittore di file restituito da dio_open().

Valori restituiti

No value is returned.

Esempi

Esempio 1. Chiudere un descrittore di file
<?php $fd = dio_open('/dev/ttyS0', O_RDWR); dio_close($fd); ?>

Vedere anche:

dio_open()

dio_fcntl

(PHP 4 >= 4.2.0, PHP 5 <= 5.0.4)

dio_fcntl -- Esegue la funzione C fcntl su un descrittore di file

Descrizione

mixed dio_fcntl ( resource fd, int cmd [, mixed args] )

La funzione dio_fcntl() esegue le operazioni specificate dal parametro cmd sul descrittore di file fd. Qualora i comandi richiedano informazioni addizionali occorre valorizzare args con tali informazioni.

Nota: Questa funzione non è implementata su piattaforme Windows

Elenco dei parametri

fd

Descrittore di file restituito da dio_open().

cmd

Può indicare una delle seguenti operazioni:

F_SETLK - imposta o azzera un lock. Se il lock è impostato da un'altro processo la funzione dio_fcntl() restituisce -1.
F_SETLKW - come F_SETLK, ma nel caso in cui il lock sia impostato da un'altro processo la funzione dio_fcntl() attende sino a quando il blocco non viene rimosso.
F_GETLK - la dio_fcntl() restituisce un array associativo (come descritto precedentemente) se qualche altro processo impedisce il lock. Se non vi sono problemi la chiave "type" sarà impostata a F_UNLCK.
F_DUPFD - trova il più piccolo numero di descrittore di file disponibile che sia maggiore o uguale rispetto ad args e lo restituisce.
F_SETFL - Imposta i flag del descrittore di file al valore specificato da args. Tale valore può essere O_APPEND, O_NONBLOCK oppure O_ASYNC. Per utilizzare O_ASYNC occorre utilizzare l'estensione PCNTL.

args

Il parametro args è un array associativo, nei casi in cui cmd è impostato a F_SETLK oppure a F_SETLLW, contiene le seguenti chiavi:

"start" - offset da cui comincia il lock
"length" - dimensione dell'area bloccata, zero significa fine file
"wenth" - a cosa l_start è relativo: può valere SEEK_SET, SEEK_END o SEEK_CUR
"type" - tipo di lock: può essere F_RDLCK (lock in lettura), F_WRLCK (lock in scrittura) oppure F_UNLCK (rimozione del lock)

Valori restituiti

Restituisce il valore della chiamata C.

Esempi

Esempio 1. Impostare e cancellare un 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); ?>

dio_open

(PHP 4 >= 4.2.0, PHP 5 <= 5.0.4)

dio_open -- Apre un nuovo file nella modalità specificata da flags e i permessi indicati in mode

Descrizione

resource dio_open ( string filename, int flags [, int mode] )

La funzione dio_open() apre un file e restituisce un nuovo descrittore di file per questo.

Elenco dei parametri

filename

Il file aperto.

flags

Il parametro flags può contenere qualsiasi combinazione dei seguenti valori:

O_CREAT - crea un file, se questo non esiste già.
O_EXCL - se sono impostati sia O_CREAT e sia O_EXCL, la funzione dio_open() fallisce se il file esiste.
O_TRUNC - se il file esiste, ed è aperto in scrittura, il file verrà portato a lunghezza zero.
O_APPEND - nelle operazioni di scrittura, scrive i dati alla fine del file.
O_NONBLOCK - imposta la modalità non blocking.

mode

Se flags vale O_CREAT, allora il parametro mode imposta la modalità del file (permessi di creazione).

O_RDONLY - apre il file per accessi in lettura.
O_WRONLY - apre il file in scrittura.
O_RDWR - apre il file sia in lettura sia in scrittura.

Valori restituiti

Restituisce un descrittore di file, oppure FALSE in caso di errore.

Esempi

Esempio 1. Apertura di un descrittore di file

<?php

$fd = dio_open('/dev/ttyS0', O_RDWR | O_NOCTTY | O_NONBLOCK);

dio_close($fd);
?>

Vedere anche:

dio_close()

dio_read

(PHP 4 >= 4.2.0, PHP 5 <= 5.0.4)

dio_read -- Legge n bytes da un descrittore di file

Descrizione

string dio_read ( resource fd [, int len] )

La funzione dio_read() legge e restituisce len bytes dal file indicato dal descrittore fd.

Elenco dei parametri

fd: Descrittore di file restituito da dio_open().
len: Numero di byte da leggere. Se non indicato dio_read() legge blocchi da un 1k.

Valori restituiti

I byte letti da fd.

Vedere anche:

dio_write()

dio_seek

(PHP 4 >= 4.2.0, PHP 5 <= 5.0.4)

dio_seek -- Si posiziona al byte pos del file indicato da fd

Descrizione

int dio_seek ( resource fd, int pos [, int whence] )

La funzione dio_seek() viene utilizzata per modificare la posizione nel file indicato dal descrittore fd.

Elenco dei parametri

fd

Descrittore di file restituito da dio_open().

pos

La nuova posizione.

whence

specifica come debba essere interpretata la posizione indicata da pos:

SEEK_SET (default) - Indica che pos è determinato dall'inizio del file.
SEEK_CUR - Indica che pos è il numero di caratteri dalla posizione attuale. Questo valore può essere positivo o negativo.
SEEK_END - Indica che pos è il numero di caratteri dalla fine del file. Un valore negativo specifica una posizione all'interno dell'estensione del file; un valore positivo specifica una posizione oltre la fine corrente del file. Se si specifica una posizione oltre la fine del file, e vi si scrive dei dati, il file sarà allungato e riempito di zero fino a quella posizione.

Valori restituiti

Esempi

Esempio 1. Posizionamento in un file
<?php $fd = dio_open('/dev/ttyS0', O_RDWR); dio_seek($fd, 10, SEEK_SET); // Si posiziona a 10 caratteri dall'inizio del file dio_seek($fd, -2, SEEK_CUR); // Si posiziona a 8 caratteri dall'inizio del file dio_seek($fd, -5, SEEK_END); // Si posiziona a 5 caratteri dalla fine del file dio_seek($fd, 10, SEEK_END); // Si posiziona a 10 caratteri dopo la fine del file // i 10 caratteri tra la fine del file e la posizione corrente // sono riempiti con zero. dio_close($fd); ?>

dio_stat

(PHP 4 >= 4.2.0, PHP 5 <= 5.0.4)

dio_stat -- Restituisce le informazioni relative al file indicato da fd

Descrizione

array dio_stat ( resource fd )

La funzione dio_stat() restituisce le informazioni sul dato descrittore di file.

Elenco dei parametri

fd: Descrittore di file restituito da dio_open().

Valori restituiti

Restituisce un array associativo contenente le seguenti chiavi:

"device" - device
"inode" - inode
"mode" - mode
"nlink" - numero di link
"uid" - user id
"gid" - group id
"device_type" - device type (se inode device)
"size" - total size in bytes
"blocksize" - blocksize
"blocks" - dimensione totale in byte
"atime" - data dell'ultimo accesso
"mtime" - data dell'ultima modifica
"ctime" - data dell'ultimo cambiamento

Se si verifica un errore la funzione dio_stat() restituisce NULL.

dio_tcsetattr

(PHP 4 >= 4.3.0, PHP 5 <= 5.0.4)

dio_tcsetattr -- Imposta gli attributi terminale e la velocità per una porta seriale

Descrizione

void dio_tcsetattr ( resource fd, array options )

La funzione dio_tcsetattr() imposta gli attributi di terminale e la velocità della porta aperta fd.

Nota: Questa funzione non è implementata su piattaforme Windows

Elenco dei parametri

fd

Descrittore di file restituito da dio_open().

options

Attualmente le opzioni disponibili sono:

'baud' - velocità della porta - può essere 38400,19200,9600,4800,2400,1800,1200,600,300,200,150,134,110,75 oppure 50, il valore di default è 9600
'bits' - bit di dati - può essere 8,7,6 oppure 5 il valore di default è 8.
'stop' - bit di stop - può essere 1 o 2 il valore di default è 1.
'parity' - può essere 0,1 o 2 il valore di default è 0.

Valori restituiti

No value is returned.

Esempi

Esempio 1. Esempio di impostazione della velocità di una porta seriale
<?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; } } ?>

dio_truncate

(PHP 4 >= 4.2.0, PHP 5 <= 5.0.4)

dio_truncate -- Tronca il file indicato da fd ad un numero di byte specificato

Descrizione

bool dio_truncate ( resource fd, int offset )

La funzione dio_truncate() tronca il file indicato da fd ad una lunghezza massima di offset bytes.

Se in precedenza il file ha una dimensione maggiore, i dati in eccesso sono persi. Al contrario se il file è più corto, non è specificato se si debba lasciarlo inalterato o debba essere allungato. Nell'ultimo caso la parte aggiunta viene riempita a zero.

Nota: Questa funzione non è implementata su piattaforme Windows

Elenco dei parametri

fd: Descrittore di file restituito da dio_open().
offset: Posizione in byte.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

dio_write

(PHP 4 >= 4.2.0, PHP 5 <= 5.0.4)

dio_write -- Scrive dati sul file indicato da fd con la possibilità di troncarne la lunghezza

Descrizione

int dio_write ( resource fd, string data [, int len] )

La funzione dio_write() scrive fino a len bytes da data nel file fd.

Elenco dei parametri

fd: Descrittore di file restituito da dio_open().
data: I dati scritti.
len: Lunghezza dei dati da scrivere in byte. Se non indicato, la funzione scrive tutti i dati nel file indicato.

Valori restituiti

La funzione restituisce il numero di byte scritti in fd.

Vedere anche:

dio_read()

XXIX. Funzioni per le directory

Introduzione

Requisiti

Non sono necessarie librerie esterne per utilizzare questo modulo.

Installazione

Non è necessaria nessuna installazione per usare queste funzioni, esse fanno parte del core di PHP.

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Tipi di risorse

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

DIRECTORY_SEPARATOR (string)
PATH_SEPARATOR (string)

Nota: La costante PATH_SEPARATOR è stata inserita dalla versione 4.3.0-RC2.

Vedere anche:

Per funzioni correlate, quali dirname(), is_dir(), mkdir() e rmdir(), vedere la sezione Filesystem.

Sommario
chdir -- cambia directory
chroot -- Cambia la direcory di root
dir -- Classe directory
closedir -- Chiude l'handle della directory
getcwd -- Restituisce la directory di lavoro in uso
opendir -- Apre l'handle della directory
readdir -- Legge una voce dall'handle della directory
rewinddir -- Riavvolge l'handle della directory
scandir -- List files and directories inside the specified path

chdir

(PHP 3, PHP 4, PHP 5)

chdir -- cambia directory

Descrizione

bool chdir ( string directory )

Cambia la directory in uso da parte del PHP in directory. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempio 1. Esempio di uso di chdir()
<?php // directory corrente echo getcwd() . "\n"; chdir('public_html'); // directory corrente echo getcwd() . "\n"; ?>
Il precedente esempio visualizzerà:
/home/vincent /home/vincent/public_html

Nota: Quando safe-mode è abilitato, PHP controlla che la directory nella quale si sta lavorando, abbia lo stesso UID dello script che è in esecuzione.

Vedere anche getcwd().

chroot

(PHP 4 >= 4.0.5, PHP 5)

chroot -- Cambia la direcory di root

Descrizione

bool chroot ( string directory )

Cambia la directory di root del processo in esecuzione in directory. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Questa funzione è disponibile soltanto se il sistema la supporta e se si sta utilizzando il PHP come CLI, CGI o Embed SAPI.

Nota: chroot() richiede i privilegi di root.

Nota: Questa funzione non è implementata su piattaforme Windows

dir

(PHP 3, PHP 4, PHP 5)

dir -- Classe directory

Descrizione

class dir {

dir ( string directory )

string path

resource handle

string read ( void )

void rewind ( void )

void close ( void )

}

Un meccanismo pseudo orientato agli oggetti per leggere una directory. La directory data è aperta. Due proprietà sono disponibili nonappena la directory è stata aperta. La proprietà handle può essere usata in congiunzione ad altre funzioni relative alle directory, quali readdir(), rewinddir() e closedir(). La proprietà path è impostata alla directory che è stata aperta. Sono disponibili tre metodi: read (leggi), rewind (riavvolgi) e close (chiudi).

Fare attenzione al modo in cui il valore restituito dalla funzione dir() è controllato nell'esempio sotto riportato. Controlliamo esplicitamente che il valore restituito sia identico a (uguale a e dello stesso tipo di (fare riferimento a Comparison Operators per maggiori informazioni) FALSE altrimenti, ogni risultato il cui nome non venga valutato FALSE farà interrompere il ciclo.
Esempio 1. esempio dir()
<?php $d = dir("/etc"); echo "Handle: " . $d->handle . "<br />\n"; echo "Path: " . $d->path . "<br />\n"; while ($entry = $d->read()) { echo $entry."<br />\n"; } $d->close(); ?>

Nota: L'ordine nel quale vengono restituiti i dati dal metodo read è dipendente dal sistema usato.

Nota: Questo definisce la classe interna Directory, ciò significa che non sarà possibile definire una nuova classe con lo stesso nome. Per una lista completa delle classi predefinite presenti in PHP, fare riferimento a Predefined Classes.

closedir

(PHP 3, PHP 4, PHP 5)

closedir -- Chiude l'handle della directory

Descrizione

void closedir ( resource dir_handle )

Chiude il flusso directory indicato da dir_handle. Il flusso deve essere stato aperto in precedenza da opendir().

getcwd

(PHP 4, PHP 5)

getcwd -- Restituisce la directory di lavoro in uso

Descrizione

string getcwd ( void )

Restituisce la directory di lavoro in uso al momento o FALSE in caso di errore.

Nota: In alcune versioni di Unix, getcwd() restituirà FALSE se una delle directory superiori non ha i permessi di lettura o di ricerca abilitati, anche se li ha la directory corrente Vedere chmod() per maggiori infprmazioni sui permessi.

scandir -- List files and directories inside the specified path

Descrizione

array scandir ( string directory [, int sorting_order [, resource context]] )

Returns an array of files and directories from the directory.

Elenco dei parametri

directory: The directory that will be scanned.
sorting_order: By default, the sorted order is alphabetical in ascending order. If the optional sorting_order is used (set to 1), then the sort order is alphabetical in descending order.
context: For a description of the context parameter, refer to the streams section of the manual.

Valori restituiti

Returns an array of filenames on success, or FALSE on failure. If directory is not a directory, then boolean FALSE is returned, and an error of level E_WARNING is generated.

Esempi

Esempio 1. A simple scandir() example
<?php $dir = '/tmp'; $files1 = scandir($dir); $files2 = scandir($dir, 1); print_r($files1); print_r($files2); ?>
Il precedente esempio visualizzerà qualcosa simile a:
Array ( [0] => . [1] => .. [2] => bar.php [3] => foo.txt [4] => somedir ) Array ( [0] => somedir [1] => foo.txt [2] => bar.php [3] => .. [4] => . )

Esempio 2. PHP 4 alternatives to scandir()
<?php $dir = "/tmp"; $dh = opendir($dir); while (false !== ($filename = readdir($dh))) { $files[] = $filename; } sort($files); print_r($files); rsort($files); print_r($files); ?>
Il precedente esempio visualizzerà qualcosa simile a:
Array ( [0] => . [1] => .. [2] => bar.php [3] => foo.txt [4] => somedir ) Array ( [0] => somedir [1] => foo.txt [2] => bar.php [3] => .. [4] => . )

Note

Suggerimento: È possibile utilizzare una URL come un nome di file con questa funzione se fopen wrappers è stata abilitata. Per maggiori informazioni su come specificare i nomi di file vedere fopen() e Appendice M per avere la lista dei protocolli URL supportati.

Vedere anche:

opendir()

readdir()

glob()

is_dir()

sort()

XXX. DOM Functions

Introduzione

L'estensione DOM è la sostituzione dell'estensione DOM XML del PHP 4. Questo modulo continua a contenere diverse vecchie funzioni, ma non dovrebbereo essere più utilizzate. In particolar modo si dovrebbe evitare le funzioni che non sono orientate agli oggetti.

L'estensione permette di lavorare su un documento XML con le API DOM.

Installazione

Non è necessaria nessuna installazione per usare queste funzioni, esse fanno parte del core di PHP.

Classi predefinite

Le APi del modulo seguono lo standard DOM Level 2 il più fedelmente possibile. Di conseguenza la API sono completamente ad oggetti. E' consigliabile avere a portata di mano lo standard DOM quando si utilizza questo modulo.

Questo modulo definisce diverse classi, che sono illustrate nelle seguenti tabelle. Quelle con una corrispondente classe nello standard DOM sono chia,ate DOMxxx.

DOMAttr

Estende DOMNode. L'interfaccia DOMAttr rappresenta un attributo dell'oggetto DOMElement.

Costruttori

DOMAttr->__construct() - costruisce un nuovo oggetto DOMAttr

Metodi

DOMAttr->isId() - Verifica se l'attributo è un ID definito

Proprietà

Tabella 1.

Nome	Tipo	Sola lettura	Descrizione
name	string	si	Nome dell'attributo
ownerElement	DOMElement	sì	Elemento che contiene l'attributo
schemaTypeInfo	bool	sì	Non ancora impementato, ritorna sempre `NULL`
specified	bool	sì	Non ancora impementato, ritorna sempre `NULL`
value	string	no	Valore dell'attributo

DOMCharacterData

Espande DOMNode.

Metodi

DOMCharacterData->appendData() - Aggiunge un testo alla fine dei dati di un nodo
DOMCharacterData->deleteData() - Rimuove un range di caratteri dal nodo
DOMCharacterData->insertData() - Inserisce una stringa alla posizione indicata
DOMCharacterData->replaceData() - Sostituisce una posizione di testo nel nodo DOMCharacterData
DOMCharacterData->substringData() - Estrai una porzione di dati dal nodo

Proprietà

Tabella 2.

Nome	Tipo	Sola lettura	Descrizione
data	string	no	Contenuto del nodo
length	int	sì	Lunghezza del contenuto

DOMComment

Espande DOMCharacterData.

Costruttori

DOMComment->__construct() - costruisce un nuovo oggetto DOMComment

DOMDocument

Espande DOMNode.

Costruttori

DOMDocument->__construct() - costruisce un nuovo oggetto DOMDocument

Metodi

DOMDocument->createAttribute() - Crea un nuovo attributo
DOMDocument->createAttributeNS() - Crea un nuovo nodo attributo con associato uno spazio dei nomi
DOMDocument->createCDATASection() - Crea un nuovo nodo cdata
DOMDocument->createComment() - Crea un nuovo nodo commento
DOMDocument->createDocumentFragment() - Crea un nuovo nodo frammento
DOMDocument->createElement() - Crea un nuovo nodo elemento
DOMDocument->createElementNS() - Crea un nuovo nodo elemento con associato uno spazio dei nomi
DOMDocument->createEntityReference() - Crea un nuovo nodo entità
DOMDocument->createProcessingInstruction() - CRea un nuovo nodo PI
DOMDocument->createTextNode() - Crea un nuovo nodo testo
DOMDocument->getElementById() - Cerca un elemento con un certo ID
DOMDocument->getElementsByTagName() - Cerca tutti gli elementi per un dato tag
DOMDocument->getElementsByTagNameNS() - Cerca tutti gli elementi per un dato tag in un specifico spazio dei nomi
DOMDocument->importNode() - Importa il nodo nel documento corrente
DOMDocument->load() - Carica un file XML
DOMDocument->loadHTML() - Carica un documento HTML da una stringa
DOMDocument->loadHTMLFile() - Carica un file HTML
DOMDocument->loadXML() - Carica un documento XML da una stringa
DOMDocument->normalize() - Normalizza il documento
DOMDocument->relaxNGValidate() - Esegue una validazione relaxNG sul documento
DOMDocument->relaxNGValidateSource() - Esegue una validazione relaxNG sul documento
DOMDocument->save() - Scrive l'albero XML in un file
DOMDocument->saveHTML() - Scarica il docuemnto interno in una stringa formattato in HTML
DOMDocument->saveHTMLFile() - Scarica il docuemnto interno in un file formattato in HTML
DOMDocument->saveXML() - Scrive l'albero XML in un file in una stringa
DOMDocument->schemaValidate() - Valida il documento in base ad uno schema
DOMDocument->schemaValidateSource() - Valida il documento in base ad uno schema
DOMDocument->validate() - Valida il documento in base ad al suo DTD
DOMDocument->xinclude() - Sostituisce gli XIncludes in un oggetto DOMDocument

Proprietà

Tabella 3.

Nome	Tipo	Sola lettura	Descrizione
actualEncoding	string	sì
config	DOMConfiguration	sì
doctype	DOMDocumentType	sì	Dichiarazione del tipo documento associato al docuemnto.
documentElement	DOMElement	sì	Attributo di convenienza per accedere direttamente al nodo figlio, che è l'elemento del documento.
documentURI	string	no	Luogo del documento oppure `NULL` se indefinito.
encoding	string	no
formatOutput	bool	no
implementation	DOMImplementation	sì	L'oggetto DOMImplementation che gestisce questo documento.
preserveWhiteSpace	bool	no	Non rimuovere gli spazi ridondanti. Default `TRUE`.
recover	bool	no
resolveExternals	bool	no	Impostare a `TRUE` per caricare le entità esterne dalla dichiarazione doctype. Questo è utile per includere entità di caratteri nel documento XML.
standalone	bool	no
strictErrorChecking	bool	no	Genera un DOMException in caso di errore. Default `TRUE`.
substituteEntities	bool	no
validateOnParse	bool	no	Carica e valida nei confronti della DTD. Default `FALSE`.
version	string	no
xmlEncoding	string	sì	L'attributo specifica, come parte della dichiarazione XML, la codifica del docuemnto. Vale `NULL` se non specificato oppure quando non è noto, come quando il documento è creato in memoria.
xmlStandalone	bool	no	Attributo che specifica, come parte della dichiarazione XML, se il documento è standalone. Vale `FALSE` se non specificato.
xmlVersion	string	no	Attributo che specifica, come parte della dichiarazione XML, il numero di versione del documento. Se non viè una dichiarazione e se il documento supporta le spcifiche "XML", vale "1.0".

DOMDocumentType

Espande DOMNode

Ciascun DOMDocument possiede un attributo doctype il cui valore può essere o NULL o un oggetto DOMDocumentType.

Proprietà

Tabella 4.

Nome	Tipo	Sola lettura	Descrizione
publicId	string	sì	Identificatore pubblico del subset esterno.
systemId	string	sì	Identificatore di sistema del subset esterno. Può essere un URI assoluto o meno.
name	string	sì	Il nome della DTD; ad esempio il nome che segue immediatamente la parola chiave `DOCTYPE`.
entities	DOMNamedNodeMap	sì	Un oggetto DOMNamedNodeMap che contiene le entità generali, sia interne che esterne, dichiarate nella DTD.
notations	DOMNamedNodeMap	sì	Un oggetto DOMNamedNodeMap contenente le notazioni dichiarate nella DTD.
internalSubset	string	sì	SubSet interno definito come stringa, oppure null se non vi è nulla. Questo non contiene le parentesi quadre di delimitazione.

DOMElement

Espande DOMNode.

Costruttori

DOMElement->__construct() - costruisce un nuovo oggetto DOMElement

Metodi

DOMElement->getAttribute() - Restituisce il valore di un attributo
DOMElement->getAttributeNode() - Restituisce il nodo attributo
DOMElement->getAttributeNodeNS() - Restituisce il nodo attributo
DOMElement->getAttributeNS() - Restituisce il valore di un attributo
DOMElement->getElementsByTagName() - Restituisce gli elementi in base al nome tag
DOMElement->getElementsByTagNameNS() - Restituisce gli elementi in base all UTRI dello spazio dei nomi ed il nome locale
DOMElement->hasAttribute() - Verifica se l'attributo esiste
DOMElement->hasAttributeNS() - Verifica se l'attributo esiste
DOMElement->removeAttribute() - Rimuove l'attributo
DOMElement->removeAttributeNode() - Rimuove l'attributo
DOMElement->removeAttributeNS() - Rimuove l'attributo
DOMElement->setAttribute() - Aggiunge un nuovo attributo
DOMElement->setAttributeNode() - Aggiunge un nuovo nodo attributo all'elemento
DOMElement->setAttributeNodeNS() - Aggiunge un nuovo nodo attributo all'elemento
DOMElement->setAttributeNS() - Aggiunge un nuovo attributo

Proprietà

Tabella 5.

Nome	Tipo	Sola lettura	Descrizione
schemaTypeInfo	bool	sì	Non ancora implementato, restituisce sempre `NULL`
tagName	string	sì	Nome dell'elemento

DOMEntity

Espande DOMNode

Questa interfaccia rappresenta una entità nota, sia interpretata che no, in un documento XML.

Proprietà

Tabella 6.

Nome	Tipo	Sola lettura	Descrizione
publicId	string	sì	Identificatore pubblico associato all'entità, se indicato, altrimenti `NULL`.
systemId	string	sì	Identificatore di sistema associato all'entità, se indicato, altrimenti `NULL`. Può essere un URI assoluto.
notationName	string	sì	Per le entità non interpretate, il nome della notazione dell'entità. Per le entità interpretate vale `NULL`.
actualEncoding	string	no	Attributo che indica la codifica utilizzata per questa entità al momento dell'intepretazione, in caso di interpretazione di entità esterne. Vale `NULL` se si tratta di un'entità interna, o se non è noto.
encoding	string	sì	Attributo che indica, come parte del testo di dichiarazione, la codifica dell'entità, in caso di entità esterna. Negli altri casi vale `NULL`.
version	string	sì	Attributo che indica, come parte del testo di dichiarazione, il numero di versione di questa entità, in caso di entità esterna. Altrimenti `NULL`.

DOMEntityReference

Espande DOMNode.

Costruttori

DOMAttr->__construct() - costruisce un nuovo oggetto DOMEntityReference

DOMException

Le funzioni DOM, in casi particolari, generano delle eccezioni, ad esempio quando un'operazione non può essere eseguita per motivi logici.

Vedere anche Capitolo 20.

Proprietà

Tabella 7.

Nome	Tipo	Sola lettura	Descrizione
code	int	sì	Intero indicante il tipo di errore generato

DOMImplementation

L'interfaccia DOMImplementation fornisce diversi metodi per eseguire operazioni che sono indipendenti da qualsiasi istanza del modello ad oggetti del documento.

Costruttori

DOMImplementation->__construct() - costruisce un nuovo oggetto DOMImplementation

Metodi

DOMImplementation->createDocument() - Crea un nuovo oggetto DOM Document del tipo specificato con il suo elemento documento
DOMImplementation->createDocumentType() - Crea un oggetto DOMDocumentType vuoto
DOMImplementation->hasFeature() - Verifica se l'implementazione DOM supporta specifiche caratteristiche

DOMNode

Metodi

DOMNode->appendChild() - Aggiunge un nuovo nodo figlio alla fine dei nodi figli
DOMNode->cloneNode() - Clona un nodo
DOMNode->hasAttributes() - Verifica se il nodo ha attributi
DOMNode->hasChildNodes() - Verifica se il nodo ha figli
DOMNode->insertBefore() - Aggiunge un nuovo figlio prima del nodo indicato
DOMNode->isSameNode() - Indica se due nodi sono lo stesso nodo
DOMNode->isSupported() - Verifica se la caratteristica chiesta è supportata dalla versione
DOMNode->lookupNamespaceURI() - Restituisce l'URI dello spazio dei nomi del nodo in base al suo prefisso
DOMNode->lookupPrefix() - Restituisce il prefisso dello spazio dei nomi del nodo in base all'URI dello spazio dei nomi
DOMNode->normalize() - Normalizza il nodo
DOMNode->removeChild() - Rimuove un nodo figlio dall'elenco dei nodi figli
DOMNode->replaceChild() - Sostituisce un nodo figlio

Proprietà

Tabella 8.

Nome	Tipo	Sola lettura	Descrizione
nodeName	string	sì	Restituisce un nome più accurato per il tipo di nodo.
nodeValue	string	no	Valore di questo nodo, dipende dal tipo.
nodeType	int	sì	Tipo di nodo. Una delle costanti XML_xxx_NODE predefinite.
parentNode	DOMNode	sì	Nodo genitore di questo nodo.
childNodes	DOMNodeList	sì	Un oggetto DOMNodeList che contiene tutti i nodi figli di questo nodo. Se non vi sono nodi figli, questa è un DOMNodeList vuoto.
firstChild	DOMNode	sì	Il primo figlio di questo nodo. Se tale nodo non esiste, restituisce `NULL`.
lastChild	DOMNode	sì	L'ultimo figlio di questo nodo. Se tale nodo non esiste, restituisce `NULL`.
previousSibling	DOMNode	sì	Il nodo immediatamente precedente a questo. Se tale nodo non esiste, restituisce `NULL`.
nextSibling	DOMNode	sì	Il nodo immediatamente seguente a questo. Se tale nodo non esiste, restituisce `NULL`.
attributes	DOMNamedNodeMap	sì	Un oggetto DOMNamedNodeMap contenente gli attributi di questo nodo (se si tratta di un DOMElement) oppure `NULL`.
ownerDocument	DOMDocument	sì	L'oggetto DOMDocument associato a questo nodo.
namespaceURI	string	sì	L'URI dello spazio dei nomi di questo nodo, oppure `NULL` se non specificato.
prefix	string	no	Prefisso dello spazio dei nomi del nodo, oppure `NULL` se non specificato.
localName	string	sì	Restituisce la parte locale del nome qualificato del nodo.
baseURI	string	sì	L'URI assoluto del nodo oppure `NULL` se l'implementazione non è in grado di ottenere l'URI assoluto.
textContent	string	no	Questo attributo restituisce il testo contenuto nel nodo e nei suoi discendenti.

DOMNodeList

Metodi

DOMNodelist->item() - Recupera il nodo indicato dall'indice

Proprietà

Tabella 9.

Nome	Tipo	Sola lettura	Descrizione
length	int	sì	Numero di nodi nella lista. Il range valido per l'indice varia tra 0 e `length - 1` compresi.

DOMNotation

Espande DOMNode

Proprietà

Tabella 10.

Nome	Tipo	Sola lettura	Descrizione
publicId	string	sì
systemId	string	sì

DOMProcessingInstruction

Espande DOMNode.

Costruttori

DOMProcessingInstruction->__construct() - costruisce un nuovo oggetto DOMProcessingInstruction

Proprietà

Tabella 11.

Nome	Tipo	Sola lettura	Descrizione
target	string	sì
data	string	no

DOMText

Espande DOMCharacterData.

Costruttori

DOMText->__construct() - costruisce un nuovo oggetto DOMText

Metodi

DOMText->isWhitespaceInElementContent() - Indica se questo nodo contiene degli spazi
DOMText->splitText() - Divide il nodo in due alla posizione indicata

Proprietà

Tabella 12.

Nome	Tipo	Sola lettura	Descrizione
wholeText	string	sì

DOMXPath

Costruttori

DOMXPath->__construct() - construct a new DOMXPath object

Metodi

DOMXPath->registerNamespace() - Registers the namespace with the DOMXpath object
DOMXPath->evaluate() - Evaluates the given XPath expression and returns a typed result if possible
DOMXPath->query() - Evaluates the given XPath expression

Proprietà

Tabella 13.

Nome	Tipo	Sola lettura	Descrizione
document	DOMDocument

Esempi

Many examples in this reference require an XML file. We will use book.xml that contains the following:

Esempio 1. chapter.xml
<?xml version="1.0" encoding="iso-8859-1"?> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ ]> <book id="listing"> <title>My lists</title> <chapter id="books"> <title>My books</title> <para> <informaltable> <tgroup cols="4"> <thead> <row> <entry>Title</entry> <entry>Author</entry> <entry>Language</entry> <entry>ISBN</entry> </row> </thead> <tbody> <row> <entry>The Grapes of Wrath</entry> <entry>John Steinbeck</entry> <entry>en</entry> <entry>0140186409</entry> </row> <row> <entry>The Pearl</entry> <entry>John Steinbeck</entry> <entry>en</entry> <entry>014017737X</entry> </row> <row> <entry>Samarcande</entry> <entry>Amine Maalouf</entry> <entry>fr</entry> <entry>2253051209</entry> </row>  </tbody> </tgroup> </informaltable> </para> </chapter> </book>

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

Tabella 14. Costanti XML

Costante	Valore	Descrizione
`XML_ELEMENT_NODE` (integer)	1	Il nodo è un DOMElement
`XML_ATTRIBUTE_NODE` (integer)	2	Il nodo è un DOMAttr
`XML_TEXT_NODE` (integer)	3	Il nodo è un DOMText
`XML_CDATA_SECTION_NODE` (integer)	4	Il nodo è un oggetto DOMCharacterData
`XML_ENTITY_REF_NODE` (integer)	5	Il nodo è un oggetto DOMEntityReference
`XML_ENTITY_NODE` (integer)	6	Il nodo è un DOMEntity
`XML_PI_NODE` (integer)	7	Il nodo è un DOMProcessingInstruction
`XML_COMMENT_NODE` (integer)	8	Il nodo è un DOMComment
`XML_DOCUMENT_NODE` (integer)	9	Il nodo è un DOMDocument
`XML_DOCUMENT_TYPE_NODE` (integer)	10	Il nodo è un oggetto DOMDocumentType
`XML_DOCUMENT_FRAG_NODE` (integer)	11	Il nodo è un oggetto DOMDocumentFragment
`XML_NOTATION_NODE` (integer)	12	Il nodo è un oggetto DOMNotation
`XML_HTML_DOCUMENT_NODE` (integer)	13
`XML_DTD_NODE` (integer)	14
`XML_ELEMENT_DECL_NODE` (integer)	15
`XML_ATTRIBUTE_DECL_NODE` (integer)	16
`XML_ENTITY_DECL_NODE` (integer)	17
`XML_NAMESPACE_DECL_NODE` (integer)	18
`XML_ATTRIBUTE_CDATA` (integer)	1
`XML_ATTRIBUTE_ID` (integer)	2
`XML_ATTRIBUTE_IDREF` (integer)	3
`XML_ATTRIBUTE_IDREFS` (integer)	4
`XML_ATTRIBUTE_ENTITY` (integer)	5
`XML_ATTRIBUTE_NMTOKEN` (integer)	7
`XML_ATTRIBUTE_NMTOKENS` (integer)	8
`XML_ATTRIBUTE_ENUMERATION` (integer)	9
`XML_ATTRIBUTE_NOTATION` (integer)	10

Tabella 15. Costanti DOMException

Costante	Valore	Descrizione
`DOM_INDEX_SIZE_ERR` (integer)	1	Se l'indice o la dimensione sono negativi, o maagiori del valore ammesso.
`DOMSTRING_SIZE_ERR` (integer)	2	Se il range di testo indicato non rientra nell'oggetto DOMString.
`DOM_HIERARCHY_REQUEST_ERR` (integer)	3	Se il nodo è inserito in posti non attesi
`DOM_WRONG_DOCUMENT_ERR` (integer)	4	Se il nodo viene utilizzato in documenti differenti rispetto a quello che lo ha creato.
`DOM_INVALID_CHARACTER_ERR` (integer)	5	Carattere invalido o illegale.
`DOM_NO_DATA_ALLOWED_ERR` (integer)	6	Dati indicati per un nodo che non gestisce i dati.
`DOM_NO_MODIFICATION_ALLOWED_ERR` (integer)	7	Tentativo di modifica di un oggetto che non permette modifiche.
`DOM_NOT_FOUND_ERR` (integer)	8	Riferimento ad un nodo in un contesto in cui non esiste.
`DOM_NOT_SUPPORTED_ERR` (integer)	9	Tipo di oggetto oppure operazione non supportata dall'implementazione.
`DOM_INUSE_ATTRIBUTE_ERR` (integer)	10	Tentativo di aggiungere un attributo già in uso altrove.
`DOM_INVALID_STATE_ERR` (integer)	11	Utilizzo di un oggetto che non è più utilizzabile.
`DOM_SYNTAX_ERR` (integer)	12	Stringa non valida o illegale.
`DOM_INVALID_MODIFICATION_ERR` (integer)	13	Tentativo di modificare il tipo dell'oggetto sottostante.
`DOM_NAMESPACE_ERR` (integer)	14	Tentativo di creare o modficiare un oggetto in un modo che non è corretto rispetto allo spazio dei nomi.
`DOM_INVALID_ACCESS_ERR` (integer)	15	Parametro od operazione non supportati dall'oggetto.
`DOM_VALIDATION_ERR` (integer)	16	Chiamata ad un metodo tipo insertBefore oppure removeChild che renda il nodo invalido ripetto ad una 'validazione parziale'; questa eccezione comporta la mancata esecuzione dell'operazione.

Sommario
DOMAttr->__construct() -- Crea un nuovo oggetto DOMAttr
DOMAttr->isId() -- Verifica se l'attributo è un ID definito
DOMCharacterData->appendData() -- Aggiunge una stringa alla fine del testo di un nodo
DOMCharacterData->deleteData() -- Rimuove un range di caratteri da un nodo
DOMCharacterData->insertData() -- Inserisce una stringa all'offset di 16 bit indicato
DOMCharacterData->replaceData() -- Sostituisce una stringa all'interno di un nodo DOMCharacterData
DOMCharacterData->substringData() -- Estrae un tange di dati da un nodo
DOMComment->__construct() -- Crea un nuovo oggetto DOMComment
DOMDocument->__construct() -- Crea un nuovo oggetto DOMDocument
DOMDocument->createAttribute() -- Crea un nuovo attributo
DOMDocument->createAttributeNS() -- Crea un nuovo nodo attributo con associato lo spazio dei nomi
DOMDocument->createCDATASection() -- Crea un nuovo nodo cdata
DOMDocument->createComment() -- Crea un nuovo nodo di commento
DOMDocument->createDocumentFragment() -- Crea un nuovo frammento di documento
DOMDocument->createElement() -- Crea un nuovo nodo elemento
DOMDocument->createElementNS() -- Crea un nuovo nodo elemento con associato lo spazio dei nomi
DOMDocument->createEntityReference() -- Crea un nuovo nodo riferimento ad entità
DOMDocument->createProcessingInstruction() -- Crea un nuovo nodo PI
DOMDocument->createTextNode() -- Crea un nuovo nodo di testo
DOMDocument->getElementById() -- Cerca un elemento con un certo id
DOMDocument->getElementsByTagName() -- Cerca tutti gli eleemnti per un dato nome di tag
DOMDocument->getElementsByTagNameNS() -- Ricerca tutti gli elementi per un dato nome tag nello spazio dei nomi indicato.
DOMDocument->importNode() -- Importa un nodo nel documento corrente
DOMDocument->load() -- Carica un documento XML da un file
DOMDocument->loadHTML() -- Carica una pagina HTML da una stringa
DOMDocument->loadHTMLFile() -- Carica un file HTML
DOMDocument->loadXML() -- Carica un documento XML da una stringa
DOMDocument->normalize() -- Normalizza il documento
DOMDocument->relaxNGValidate() -- Esegue una validazione relaxNG sul documento
DOMDocument->relaxNGValidateSource() -- Esegue una validazione relaxNG sul documento
DOMDocument->save() -- Scarica l'albero XML interno in un file
DOMDocument->saveHTML() -- Dumps the internal document into a string using HTML formatting
DOMDocument->saveHTMLFile() -- Dumps the internal document into a file using HTML formatting
DOMDocument->saveXML() -- Dumps the internal XML tree back into a string
DOMDocument->schemaValidate() -- Validates a document based on a schema
DOMDocument->schemaValidateSource() -- Validates a document based on a schema
DOMDocument->validate() -- Valida il documento in base alla sua DTD
DOMDocument->xinclude() -- Sostituisce gli XIncludes in un oggetto DOMDocument
DOMElement->__construct() -- Crea un nuovo oggetto DOMElement
DOMElement->getAttribute() -- Restituisce il valore di un attributo
DOMElement->getAttributeNode() -- Restituisce il nodo attributo
DOMElement->getAttributeNodeNS() -- Restituisce un nodo attributo
DOMElement->getAttributeNS() -- Restituisce il valore di un attributo
DOMElement->getElementsByTagName() -- Restituisce gli elementi in base al nome del tag
DOMElement->getElementsByTagNameNS() -- Restituisce gli elementi per spazio dei nomi e nome locale
DOMElement->hasAttribute() -- Verifica se l'attributo esiste
DOMElement->hasAttributeNS() -- Verifica se esiste l'attributo
DOMElement->removeAttribute() -- Rimuove l'attributo
DOMElement->removeAttributeNode() -- Rimuove gli attributi
DOMElement->removeAttributeNS() -- Rimuove gli attributi
DOMElement->setAttribute() -- Aggiunge un nuovo attributo
DOMElement->setAttributeNode() -- Aggiunge un nuovo nodo attributo all'elemento
DOMElement->setAttributeNodeNS() -- Aggiunge un nuovo nodo attributo all'elemento
DOMElement->setAttributeNS() -- Aggiunge un nuovo attributo
DOMAttr->__construct() -- Crea un nuovo oggetto DOMEntityReference
DOMImplementation->__construct() -- Crea un nuovo oggetto DOMImplementation
DOMImplementation->createDocument() -- Crea un oggetto DOMDocument del tipo indicato con il suo elemento documento
DOMImplementation->createDocumentType() -- Crea un oggetto DOMDocumentType vuoto
DOMImplementation->hasFeature() -- Verifica se l'implementazione DOM ha una specifica caratteristica
DOMNamedNodeMap->getNamedItem() -- Recupera un nodo indicandone il nome
DOMNamedNodeMap->getNamedItemNS() -- Recupera un nodo indicando il nome locale e l'URI dello spazio dei nomi
DOMNamedNodeMap->item() -- Recupera un nodo tramite il suo indice
DOMNode->appendChild() -- Aggiunge un nuovo nodo figlio alla fine dei nodi figli
DOMNode->cloneNode() -- Clona un nodo
DOMNode->hasAttributes() -- Verifica se un nodo ha degli attributi
DOMNode->hasChildNodes() -- Verifica se un nodo ha nodi figli
DOMNode->insertBefore() -- Aggiunge un nuovo nodo figlio prima del riferimento
DOMNode->isSameNode() -- Indica se due nodi sono il medesimo nodo
DOMNode->isSupported() -- Verifica se una caratteristica è supportata dalla versione indicata
DOMNode->lookupNamespaceURI() -- Restituisce l'URI dello spazio dei nomi in base al prefisso
DOMNode->lookupPrefix() -- Resituisce il prefisso dello spazio dei nomi in base all'URI dello spazio dei nomi
DOMNode->normalize() -- Normalizza un nodo
DOMNode->removeChild() -- Rimuove un nodo figlio dalla lista dei nodi figli
DOMNode->replaceChild() -- Sostituisce un nodo figlio
DOMNodelist->item() -- Recupera il nodo indicato dall'indice
DOMProcessingInstruction->__construct() -- Crea un nuovo oggetto DOMProcessingInstruction
DOMText->__construct() -- Crea un nuovo oggetto DOMText
DOMText->isWhitespaceInElementContent() -- Indica se questo nodo di testo contiene spazi
DOMText->splitText() -- Spezza il nodo in due all'offset specificato
DOMXPath->__construct() -- Crea un nuovo oggetto DOMXPath
DOMXPath->evaluate() -- Valuta l'espressione XPath data e restituisce un risultato se possibile
DOMXPath->query() -- Valuta l'espressione XPath
DOMXPath->registerNamespace() -- Registra lo spazio dei nomi nell'oggetto DOMXpath
dom_import_simplexml -- Ottiene un'oggetto DOMElement da un'oggetto SimpleXMLElement

DOMAttr->__construct()

(no version information, might be only in CVS)

DOMAttr->__construct() -- Crea un nuovo oggetto DOMAttr

Descrizione

class DOMAttr {

__construct ( string name [, string value] )

}

Crea un nuovo oggetto DOMAttr. Questo oggetto è in sola lettura. Può essere aggiunto al documento, ma non vi possono essere aggiunti nodi fino a quando DOMDocument->createAttribute().

Elenco dei parametri

name: Nome tag dell'attributo- The tag name of the attribute.
value: Valore dell'attributo.

Esempi

Esempio 1. Esempio di creazione di un nuovo DOMAttr
<?php $dom = new DOMDocument('1.0', 'iso-8859-1'); $element = $dom->appendChild(new DOMElement('root')); $attr = $element->setAttributeNode(new DOMAttr('attr', 'attrvalue')); echo $dom->saveXML(); /* <?xml version="1.0" encoding="iso-8859-1"?><root attr="attrvalue" /> */ ?>

Vedere anche:

DOMAttr->isId()

(no version information, might be only in CVS)

DOMAttr->isId() -- Verifica se l'attributo è un ID definito

Descrizione

class DOMAttr {

bool isId ( void )

}

Questa funzione verifica se l'attributo sia un ID definito.

In base allo standard DOM, questa funzione riochiede la presenza di una DTD che definisca l'attributo ID di tipo ID. Occorre validare il documento con DOMDocument->validate() oppure DOMDocument::validateOnParse prima di utilizzare questa funzione.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 1. DOMAttr->isId() Example
<?php $doc = new DomDocument; // Occorre validare il documento prima di puntare all'id $doc->validateOnParse = true; $doc->Load('book.xml'); // Recuperiamo l'attributo chianat id del capitolo documento $attr = $doc->getElementsByTagName('chapter')->item(0)->getAttributeNode('id'); var_dump($attr->isId()); // bool(true) ?>

DOMCharacterData->appendData()

(no version information, might be only in CVS)

DOMCharacterData->appendData() -- Aggiunge una stringa alla fine del testo di un nodo

Descrizione

class DOMCharacterData {

void appendData ( string data )

}

Aggiunge la stringa data alla fine dei dati del nodo.

Elenco dei parametri

data: La stringa da aggiungere.

Valori restituiti

No value is returned.

Vedere anche:

DOMCharacterData->deleteData()

(no version information, might be only in CVS)

DOMCharacterData->deleteData() -- Rimuove un range di caratteri da un nodo

Descrizione

class DOMCharacterData {

void deleteData ( int offset, int count )

}

Rimuove un numero di caratteri pari a count a partire dalla posizione offset.

Elenco dei parametri

offset: Offset da cui partire a rimuovere.
count: Il numero di caratteri da rimuovere. Se la somma di offset e count eccede la lunghezza del testo, saranno cancellati tutti i caratteri fino alla fine.

Valori restituiti

No value is returned.

Eccezioni

DOM_INDEX_SIZE_ERR: Eccezione generata se offset è negativo oppure più grande di un numero di 16 bit, oppure se count è negativo.

Vedere anche:

DOMCharacterData->insertData()

(no version information, might be only in CVS)

DOMCharacterData->insertData() -- Inserisce una stringa all'offset di 16 bit indicato

Descrizione

class DOMCharacterData {

void insertData ( int offset, string data )

}

Inserisce la stringa data alla posizione offset.

Elenco dei parametri

offset: L'offset del carattere da cui cominciare ad inserire.
data: La stringa da inserire.

Valori restituiti

No value is returned.

Eccezioni

DOM_INDEX_SIZE_ERR: Generato se offset è negativo o se è maggiore di un numero di 16 bit.

Vedere anche:

DOMCharacterData->replaceData()

(no version information, might be only in CVS)

DOMCharacterData->replaceData() -- Sostituisce una stringa all'interno di un nodo DOMCharacterData

Descrizione

class DOMCharacterData {

void replaceData ( int offset, int count, string data )

}

Sostituisce count caratteri a partire dalla posizione offset con data.

Elenco dei parametri

offset: Offset da cui iniziare la sostituzione.
count: Numero di caratteri da sostituire. Se la somma di offset e count eccede la lunghezza, allora saranno sostituiti tutti i caratteri fino alla fine.
data: La stringa con cui sostituire i caratteri del range indicato.

Valori restituiti

No value is returned.

Eccezioni

DOM_INDEX_SIZE_ERR: Generato se offset è negativo o maggiore di un numero di 16 bit, oppure se count è negativo.

Vedere anche:

(no version information, might be only in CVS)

DOMCharacterData->substringData() -- Estrae un tange di dati da un nodo

Descrizione

class DOMCharacterData {

string substringData ( int offset, int count )

}

Restituisce la stringa richiesta.

Elenco dei parametri

offset: Offset di partenza della stringa richiesta.
count: Numero di caratteri da estrarre.

Valori restituiti

La stringa richiesta. Se la somma di offset e count supera in lunghezza i dati del nodo, considerati tutti a 16 bit, viengono restituiti tutti i dati fino alla fine.

Eccezioni

DOM_INDEX_SIZE_ERR: Generato se offset è negativo o maggiore di un numero di 16 bit, oppure se count è negativo.

Vedere anche:

DOMComment->__construct()

(no version information, might be only in CVS)

DOMComment->__construct() -- Crea un nuovo oggetto DOMComment

Descrizione

class DOMComment {

__construct ( [string value] )

}

Crea un nuovo oggetto DOMComment. Questo oggetto è in sola lettura. Può essere aggiunto ad un documento, ma non si possono inserire nodi aggiuntivi a questo nodo sino a quando il nodo è associato al docuemnto. Per creare un modo modificabile utilizzare DOMDocument->createComment().

Elenco dei parametri

value: Il testo del commento.

Esempi

Esempio 1. Esempio di creazione di un nuovo DOMComment
<?php $dom = new DOMDocument('1.0', 'iso-8859-1'); $element = $dom->appendChild(new DOMElement('root')); $comment = $element->appendChild(new DOMComment('root comment')); echo $dom->saveXML(); /* <?xml version="1.0" encoding="iso-8859-1"?><root></root> */ ?>

Vedere anche:

DOMImplementation->createDocument()

DOMDocument->__construct()

(no version information, might be only in CVS)

DOMDocument->__construct() -- Crea un nuovo oggetto DOMDocument

Descrizione

class DOMDocument {

__construct ( [string version [, string encoding]] )

}

Crea un nuovo oggetto DOMDocument.

Elenco dei parametri

version: Numero di versione del documento come parte della dichiarazione XML.
encoding: Codifica del docuemnto utilizzata nella dichisrazione XML.

Esempi

Esempio 1. Esempio di creazione di un nuovo DOMDocument
<?php $dom = new DOMDocument('1.0', 'iso-8859-1'); echo $dom->saveXML(); /* <?xml version="1.0" encoding="iso-8859-1"?> */ ?>

Vedere anche:

DOMDocument->createAttribute()

(no version information, might be only in CVS)

DOMDocument->createAttribute() -- Crea un nuovo attributo

Descrizione

class DOMDocument {

DOMAttr createAttribute ( string name )

}

Questa funzione crea una nuova istanza della classe DOMAttr. This node will not show up in the document unless it is inserted with e.g. DOMNode->appendChild().

Elenco dei parametri

name: Nome dell'attributo.

Valori restituiti

La nuova istanza di DOMAttr oppure FALSE se si verifica un errore.

Eccezioni

DOM_INVALID_CHARACTER_ERR: Generato se name contiene caratteri non validi.

Vedere anche:

DOMDocument->createAttributeNS()

(no version information, might be only in CVS)

DOMDocument->createAttributeNS() -- Crea un nuovo nodo attributo con associato lo spazio dei nomi

Descrizione

class DOMDocument {

DOMAttr createAttributeNS ( string namespaceURI, string qualifiedName )

}

Questa funzione crea una nuova istanza della classe DOMAttr. This node will not show up in the document unless it is inserted with e.g. DOMNode->appendChild().

Elenco dei parametri

namespaceURI: L' URI dello spazio dei nomi.
qualifiedName: Il nome del tag e prefisso dell'attributo nella struttura prefix:tagname.

Valori restituiti

La nuova istanza di DOMAttr oppure FALSE se si verifica un errore.

Eccezioni

DOM_INVALID_CHARACTER_ERR: Generato se qualifiedName contiene carattei non validi.
DOM_NAMESPACE_ERR: Generato se qualifiedName se è un nome malformato, oppure se qualifiedName ha un prefisso e namespaceURI vale NULL.

Vedere anche:

DOMDocument->createCDATASection()

(no version information, might be only in CVS)

DOMDocument->createCDATASection() -- Crea un nuovo nodo cdata

Descrizione

class DOMDocument {

DOMCDATASection createCDATASection ( string data )

}

Questa funzione crea una nuova istanza della classe DOMCDATASection. This node will not show up in the document unless it is inserted with e.g. DOMNode->appendChild().

Elenco dei parametri

data: Contenuto del nodo cdata.

Valori restituiti

Una nuova istanza di DOMCDATASection oppure FALSE in caso di errore.

Vedere anche:

DOMDocument->createComment()

(no version information, might be only in CVS)

DOMDocument->createComment() -- Crea un nuovo nodo di commento

Descrizione

class DOMDocument {

DOMComment createComment ( string data )

}

Questa funzione crea una nuova istanza della classe DOMComment. This node will not show up in the document unless it is inserted with e.g. DOMNode->appendChild().

Elenco dei parametri

data: Il contenuto del commento.

Valori restituiti

Una istanza di DOMComment oppure FALSE in caso di errore.

Vedere anche:

DOMDocument->createDocumentFragment()

(no version information, might be only in CVS)

DOMDocument->createDocumentFragment() -- Crea un nuovo frammento di documento

Descrizione

class DOMDocument {

DOMDocumentFragment createDocumentFragment ( void )

}

Questa funzione crea una nuova istanza della classe DOMDocumentFragment. This node will not show up in the document unless it is inserted with e.g. DOMNode->appendChild().

Valori restituiti

L'istanza DOMDocumentFragment oppure FALSE in caso di errore.

Vedere anche:

DOMDocument->createElement()

(no version information, might be only in CVS)

DOMDocument->createElement() -- Crea un nuovo nodo elemento

Descrizione

class DOMDocument {

DOMElement createElement ( string name [, string value] )

}

Questa funzione crea una nuova istanza della classe DOMElement. This node will not show up in the document unless it is inserted with e.g. DOMNode->appendChild().

Elenco dei parametri

name: Il nome del tag dell'elemento.
value: Il valore dell'elemento. Per default si crea un elemento vuoto. Il valore può essere impostato in un secondo momento tramite DOMElement->nodeValue.

Valori restituiti

Restituisce una nuova istanza della classe DOMElement oppure FALSE in caso di errore.

Eccezioni

DOM_INVALID_CHARACTER_ERR: Generato se name contiene caratteri invalidi.

Esempi

Esempio 1. Esempio di creazione di un nuovo elemento ed inserimento nel documento come root
<?php $dom = new DOMDocument('1.0', 'iso-8859-1'); $element = $dom->createElement('test', 'This is the root element!'); // inserimento dell'elemento come root (figlio del nodo documento) $dom->appendChild($element); echo $dom->saveXML(); ?>
Il precedente esempio visualizzerà:
<?xml version="1.0" encoding="iso-8859-1"?> <test>This is the root element!</test>

Vedere anche:

DOMDocument->createElementNS()

(no version information, might be only in CVS)

DOMDocument->createElementNS() -- Crea un nuovo nodo elemento con associato lo spazio dei nomi

Descrizione

class DOMDocument {

DOMElement createElementNS ( string namespaceURI, string qualifiedName [, string value] )

}

Questa funzione crea un nuovo nodo elemento con associato lo spazio dei nomi. This node will not show up in the document unless it is inserted with e.g. DOMNode->appendChild().

Elenco dei parametri

namespaceURI: L' URI dello spazio dei nomi.
qualifiedName: Un nuome qualificato pe l'elemento del tipo prefix:tagname.
value: Il valore dell'elemento. Per default si crea un elemento vuoto. Il valore può essere impostato in un secondo momento tramite DOMElement->nodeValue.

Valori restituiti

L'istanza DOMElement oppure FALSE in caso di errore.

Eccezioni

DOM_INVALID_CHARACTER_ERR: Generato se qualifiedName contiene caratteri non validi.
DOM_NAMESPACE_ERR: Generato se qualifiedName se è un nome qualificato invalido.

Esempi

Esempio 1. Esempio di creazione di un nuovo elemento ed inserimento nel documento come root
<?php $dom = new DOMDocument('1.0', 'iso-8859-1'); $element = $dom->createElementNS('http://www.example.com/XFoo', 'xfoo:test', 'This is the root element!'); // inserimento dell'elemento come root (figlio del nodo documento) $dom->appendChild($element); echo $dom->saveXML(); ?>
Il precedente esempio visualizzerà:
<?xml version="1.0" encoding="iso-8859-1"?> <xfoo:test xmlns:xfoo="http://www.example.com/XFoo">This is the root element!</xfoo:test>

Vedere anche:

DOMDocument->createEntityReference()

(no version information, might be only in CVS)

DOMDocument->createEntityReference() -- Crea un nuovo nodo riferimento ad entità

Descrizione

class DOMDocument {

DOMEntityReference createEntityReference ( string name )

}

Questa funzione crea una nuova istanza della classe DOMEntityReference. This node will not show up in the document unless it is inserted with e.g. DOMNode->appendChild().

Elenco dei parametri

name: Il contenuto del riferimento all'entità, ad esempio il riferimento all'entità meno & iniziale e ; finale.

Valori restituiti

Il nuovo DOMEntityReference oppure FALSE in caso di errore.

Eccezioni

DOM_INVALID_CHARACTER_ERR: Generato se name contiene caratteri non validi.

Vedere anche:

DOMDocument->createProcessingInstruction()

(no version information, might be only in CVS)

DOMDocument->createProcessingInstruction() -- Crea un nuovo nodo PI

Descrizione

class DOMDocument {

DOMProcessingInstruction createProcessingInstruction ( string target [, string data] )

}

Questa funzione crea una nuova istanza della classe DOMProcessingInstruction. This node will not show up in the document unless it is inserted with e.g. DOMNode->appendChild().

Elenco dei parametri

target: Il target delle itrsuzioni di processamento.
data: Il contenuto della PI.

Valori restituiti

La nuova istanza di DOMProcessingInstruction oppure FALSE in caso di errore.

Eccezioni

DOM_INVALID_CHARACTER_ERR: Generato se target contiene caratteri non validi.

Vedere anche:

(no version information, might be only in CVS)

DOMDocument->createTextNode() -- Crea un nuovo nodo di testo

Descrizione

class DOMDocument {

DOMText createTextNode ( string content )

}

Questa funzione crea una nuova istanza della classe DOMText. This node will not show up in the document unless it is inserted with e.g. DOMNode->appendChild().

Elenco dei parametri

content: Il contenuto del testo.

Valori restituiti

La nuova istanza di DOMText oppure FALSE in caso di errore.

Vedere anche:

DOMDocument->getElementsByTagName()

DOMDocument->getElementById()

(no version information, might be only in CVS)

DOMDocument->getElementById() -- Cerca un elemento con un certo id

Descrizione

class DOMDocument {

DOMElement getElementById ( string elementId )

}

Questa funzione è simile a DOMDocument->getElementsByTagName(), ma cerca un elemento per il dato id.

In base allo standard DOM, questa funzione riochiede la presenza di una DTD che definisca l'attributo ID di tipo ID. Occorre validare il documento con DOMDocument->validate() oppure DOMDocument->validateOnParse prima di utilizzare questa funzione.

Elenco dei parametri

elementId: Il valore dell'id univoco per le'elemento.

Valori restituiti

Restituisce DOMElement oppure NULL se l'elemento non è trovato.

Esempi

Esempio 1. Esempio di uso di DOMDocument->getElementById()

<?php

$doc = new DomDocument;

// Occorre validare il documento prima di puntare all'id
$doc->validateOnParse = true;
$doc->Load('book.xml');

echo "The element whose id is books is: " . $doc->getElementById('books')->tagName . "\n";

?>

Il precedente esempio visualizzerà:

The element whose id is books is: chapter

Vedere anche:

(no version information, might be only in CVS)

DOMDocument->getElementsByTagName() -- Cerca tutti gli eleemnti per un dato nome di tag

Descrizione

class DOMDocument {

DOMNodeList getElementsByTagName ( string name )

}

Questa funzione crea una nuova istanza della classe DOMNodeList contenente gli elementi con il nome tag cercato.

Elenco dei parametri

name: Il nome del tag da cercare. Il valore spaciale * indica tutti i tag.

Valori restituiti

Una nuova istanza dell'oggetto DOMNodeList contenente tutti gli elementi trovati.

Vedere anche:

DOMDocument->getElementsByTagNameNS()

(no version information, might be only in CVS)

DOMDocument->getElementsByTagNameNS() -- Ricerca tutti gli elementi per un dato nome tag nello spazio dei nomi indicato.

Descrizione

class DOMDocument {

DOMNodeList getElementsByTagNameNS ( string namespaceURI, string localName )

}

Restituicse un DOMNodeList contenente tutti gli elementi con il nome e lo spazio dei nomi indicati.

Elenco dei parametri

namespaceURI: L' URI dello spazio dei nomi degli elementi da cercare. Il valore speciale * indica tutti.
localName: Il nome locale degli elementi da cercare. Il valore speciale * indica tutti.

Valori restituiti

Un nuovo oggetto DOMNodeList contenente tutti gli elementi trovati.

Esempi

Esempio 1. Ottienet tutti gli elementi XInclude
<?php $xml = <<<EOD <?xml version="1.0" ?> <chapter xmlns:xi="http://www.w3.org/2001/XInclude"> <title>Books of the other guy..</title> <para> <xi:include href="book.xml"> <xi:fallback> <error>xinclude: book.xml not found</error> </xi:fallback> </xi:include> <include> This is another namespace </include> </para> </chapter> EOD; $dom = new DOMDocument; // Carica la stringa definita in precedenza $dom->loadXML($xml); foreach ($dom->getElementsByTagNameNS('http://www.w3.org/2001/XInclude', '*') as $element) { echo 'local name: ', $element->localName, ', prefix: ', $element->prefix, "\n"; } ?>
Il precedente esempio visualizzerà:
local name: include, prefix: xi local name: fallback, prefix: xi

Vedere anche:

DOMDocument->getElementsByTagName()

DOMDocument->importNode()

(no version information, might be only in CVS)

DOMDocument->importNode() -- Importa un nodo nel documento corrente

Descrizione

class DOMDocument {

DOMNode importNode ( DOMNode importedNode [, bool deep] )

}

Questa funzione restituisce una copia del nodo da importare e lo associa al documento corrente.

Elenco dei parametri

importedNode: Il nodo da importare.
deep: Se impostato a TRUE, questo metodo importerà in modo ricorsivo il sotto-albero di importedNode.

Valori restituiti

Il nodo copiato.

Eccezioni

DOMException è generato se il nodo non può essere importato.

DOMDocument->load()

(no version information, might be only in CVS)

DOMDocument->load() -- Carica un documento XML da un file

Descrizione

class DOMDocument {

bool load ( string filename )

}

Carica un documento XML da un file.

Questo metodo può essere richiamato staticamente per caricare e creare un oggetto DOMDocument. L'inbvocazione statica può essere utilizzata quando non occorre impostare le proprietà di DOMDocument prima del caricamento.

Elenco dei parametri

filename: Il percorso al documento XML.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 1. Creazione di un documento
<?php $doc = DOMDocument::load('book.xml'); echo $doc->saveXML(); $doc = new DOMDocument(); $doc->load('book.xml'); echo $doc->saveXML(); ?>

Vedere anche:

DOMDocument->loadXML()

DOMDocument->save()

DOMDocument->saveXML()

DOMDocument->loadHTML()

(no version information, might be only in CVS)

DOMDocument->loadHTML() -- Carica una pagina HTML da una stringa

Descrizione

class DOMDocument {

bool loadHTML ( string source )

}

La funzione esegue il parsing di una pagina HTML contenuta nella stringa source. A differenza del carico di un documento XML, il documento HTML non deve essere ben formato per potere essere caricato. Questa funzione può essere richiamata staticamente per caricare e creare un oggetto DOMDocument. L'invocazione statica può essere utilizzata quando non debbano essere impostate proprietà per DOMDocument prima del caricamento.

Elenco dei parametri

source: La stringa HTML.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 1. Creazione di un documento
<?php $doc = DOMDocument::loadHTML("<html><body>Test<br></body></html>"); echo $doc->saveHTML(); $doc = new DOMDocument(); $doc->loadHTML("<html><body>Test<br></body></html>"); echo $doc->saveHTML(); ?>

Vedere anche:

DOMDocument->loadHTMLFile()

DOMDocument->saveHTML()

DOMDocument->saveHTMLFile()

DOMDocument->loadHTMLFile()

(no version information, might be only in CVS)

DOMDocument->loadHTMLFile() -- Carica un file HTML

Descrizione

class DOMDocument {

bool loadHTMLFile ( string filename )

}

La funzione esegue il parsing del file HTML filename. A differenza del carico di un documento XML, il documento HTML non deve essere ben formato per potere essere caricato.

Questa funzione può essere richiamata staticamente per caricare e creare un oggetto DOMDocument. L'invocazione statica può essere utilizzata quando non debbano essere impostate proprietà per DOMDocument prima del caricamento.

Elenco dei parametri

filename: Il nome del file HTML.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 1. Creazione di un documento
<?php $doc = DOMDocument::loadHTMLFile("filename.html"); print $doc->saveHTML(); $doc = new DOMDocument(); $doc->loadHTMLFile("filename.html"); print $doc->saveHTML(); ?>

Vedere anche:

DOMDocument->loadHTML()

DOMDocument->saveHTML()

DOMDocument->saveHTMLFile()

DOMDocument->loadXML()

(no version information, might be only in CVS)

DOMDocument->loadXML() -- Carica un documento XML da una stringa

Descrizione

class DOMDocument {

bool loadXML ( string source )

}

Carica un documento XML da una stringa.

Elenco dei parametri

source: Stringa contenente codice XML.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 1. Creazione di un documento
<?php $doc = DOMDocument::loadXML('<root><node/></root>'); echo $doc->saveXML(); $doc = new DOMDocument(); $doc->loadXML('<root><node/></root>'); echo $doc->saveXML(); ?>

Vedere anche:

DOMDocument->load()

DOMDocument->save()

DOMDocument->saveXML()

DOMDocument->normalize()

(no version information, might be only in CVS)

DOMDocument->normalize() -- Normalizza il documento

Descrizione

class DOMDocument {

void normalize ( void )

}

Normalizza il documento.

Valori restituiti

No value is returned.

Vedere anche:

DOMNode->normalize()

DOMDocument->relaxNGValidate()

(no version information, might be only in CVS)

DOMDocument->relaxNGValidate() -- Esegue una validazione relaxNG sul documento

Descrizione

class DOMDocument {

bool relaxNGValidate ( string filename )

}

Esegue una validazione relaxNG sul documento in base allo schema RNG dato.

Elenco dei parametri

filename: File RNG.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

DOMDocument->relaxNGValidateSource()

(no version information, might be only in CVS)

DOMDocument->relaxNGValidateSource() -- Esegue una validazione relaxNG sul documento

Descrizione

class DOMDocument {

bool relaxNGValidateSource ( string source )

}

Esegue una validazione relaxNG sul documento in base alla sorgente RNG data.

Elenco dei parametri

source: Stringa contenente lo schema RNG.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

DOMDocument->saveHTMLFile()

DOMDocument->save()

(no version information, might be only in CVS)

DOMDocument->save() -- Scarica l'albero XML interno in un file

Descrizione

class DOMDocument {

mixed save ( string filename )

}

Crea un docuemnto XML dalla rappresentazione DOM. Usualmente questa funzione è chiamata dopo la creazione da zero di un nuovo documento DOM come nell'esempio seguente.

Elenco dei parametri

filename: Percorso del file in cui scrivere il documento XML.

Valori restituiti

La funzione restituisce il numero di byte scritti, oppure FALSE in caso di errore.

Esempi

Esempio 1. Salvataggio di un albero DOM in un file
<?php $doc = new DOMDocument('1.0'); // output formattato $doc->formatOutput = true; $root = $doc->createElement('book'); $root = $doc->appendChild($root); $title = $doc->createElement('title'); $title = $root->appendChild($title); $text = $doc->createTextNode('This is the title'); $text = $title->appendChild($text); echo 'Wrote: ' . $doc->save("/tmp/test.xml") . ' bytes'; // Wrote: 72 bytes ?>

Vedere anche:

DOMDocument->saveXML()

DOMDocument->load()

DOMDocument->loadXML()

DOMDocument->saveHTML()

(no version information, might be only in CVS)

DOMDocument->saveHTML() -- Dumps the internal document into a string using HTML formatting

Descrizione

class DOMDocument {

string saveHTML ( void )

}

Creates an HTML document from the DOM representation. This function is usually called after building a new dom document from scratch as in the example below.

Valori restituiti

Returns the HTML, or FALSE if an error occurred.

Esempi

Esempio 1. Saving a HTML tree into a string
<?php $doc = new DOMDocument('1.0'); // we want a nice output $doc->formatOutput = true; $root = $doc->createElement('html'); $root = $doc->appendChild($root); $head = $doc->createElement('head'); $head = $root->appendChild($head); $title = $doc->createElement('title'); $title = $head->appendChild($title); $text = $doc->createTextNode('This is the title'); $text = $title->appendChild($text); echo $doc->saveHTML(); ?>

Vedere anche:

DOMDocument->loadHTML()

DOMDocument->loadHTMLFile()

DOMDocument->saveHTMLFile()

(no version information, might be only in CVS)

DOMDocument->saveHTMLFile() -- Dumps the internal document into a file using HTML formatting

Descrizione

class DOMDocument {

int saveHTMLFile ( string filename )

}

Creates an HTML document from the DOM representation. This function is usually called after building a new dom document from scratch as in the example below.

Elenco dei parametri

filename: The path to the saved HTML document.

Valori restituiti

Returns the number of bytes written or FALSE if an error occurred.

Esempi

Esempio 1. Saving a HTML tree into a file
<?php $doc = new DOMDocument('1.0'); // we want a nice output $doc->formatOutput = true; $root = $doc->createElement('html'); $root = $doc->appendChild($root); $head = $doc->createElement('head'); $head = $root->appendChild($head); $title = $doc->createElement('title'); $title = $head->appendChild($title); $text = $doc->createTextNode('This is the title'); $text = $title->appendChild($text); echo 'Wrote: ' . $doc->saveHTMLFile("/tmp/test.html") . ' bytes'; // Wrote: 129 bytes ?>

Vedere anche:

DOMDocument->saveHTML()

DOMDocument->loadHTML()

DOMDocument->loadHTMLFile()

DOMDocument->saveXML()

(no version information, might be only in CVS)

DOMDocument->saveXML() -- Dumps the internal XML tree back into a string

Descrizione

class DOMDocument {

string saveXML ( [DOMNode node [, integer options]] )

}

Creates an XML document from the DOM representation. This function is usually called after building a new dom document from scratch as in the example below.

Elenco dei parametri

node: Use this parameter to output only a specific node without XML declaration rather than the entire document.
options: Additional Options. Currently only LIBXML_NOEMPTYTAG is supported.

Valori restituiti

Returns the XML, or FALSE if an error occurred.

Eccezioni

DOM_WRONG_DOCUMENT_ERR: Raised if node is from another document.

Log delle modifiche

Versione	Descrizione
5.1.0	Added the `options` parameter

Esempi

Esempio 1. Saving a DOM tree into a string
<?php $doc = new DOMDocument('1.0'); // we want a nice output $doc->formatOutput = true; $root = $doc->createElement('book'); $root = $doc->appendChild($root); $title = $doc->createElement('title'); $title = $root->appendChild($title); $text = $doc->createTextNode('This is the title'); $text = $title->appendChild($text); echo "Retrieving all the document:\n"; echo $doc->saveXML() . "\n"; echo "Retrieving only the title part:\n"; echo $doc->saveXML($title); ?>
Il precedente esempio visualizzerà:
Retrieving all the document: <?xml version="1.0"?> <book> <title>This is the title</title> </book> Retrieving only the title part: <title>This is the title</title>

Vedere anche:

DOMDocument->save()

DOMDocument->load()

DOMDocument->loadXML()

DOMDocument->schemaValidate()

(no version information, might be only in CVS)

DOMDocument->schemaValidate() -- Validates a document based on a schema

Descrizione

class DOMDocument {

bool schemaValidate ( string filename )

}

Validates a document based on the given schema file.

Elenco dei parametri

filename: The path to the schema.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

DOMDocument->schemaValidateSource()

(no version information, might be only in CVS)

DOMDocument->schemaValidateSource() -- Validates a document based on a schema

Descrizione

class DOMDocument {

bool schemaValidateSource ( string source )

}

Validates a document based on a schema defined in the given string.

Elenco dei parametri

source: A string containing the schema.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

(no version information, might be only in CVS)

DOMDocument->validate() -- Valida il documento in base alla sua DTD

Descrizione

class DOMDocument {

bool validate ( void )

}

Valida il documento in base alla sua DTD.

Si può anche utilizzare la proprietà validateOnParse di DOMDocument per ottenere una validazione DTD.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento. Se il documenti non ha una DTD collegata, questo metodo restituisce FALSE.

Esempi

Esempio 1. Esempio di validazione con DTD
<?php $dom = new DOMDocument; $dom->Load('book.xml'); if ($dom->validate()) { echo "Questo documento è valido!\n"; } ?>
Si può anche validare il documento mentre lo si carica:
<?php $dom = new DOMDocument; $dom->validateOnParse = true; $dom->Load('book.xml'); ?>

Vedere anche:

DOMDocument->xinclude()

(no version information, might be only in CVS)

DOMDocument->xinclude() -- Sostituisce gli XIncludes in un oggetto DOMDocument

Descrizione

class DOMDocument {

int xinclude ( [int options] )

}

Sostituisce gli XIncludes in un oggetto DOMDocument.

Nota: Poichè libxml2 risolve automaticamente le entità, quetso metodo può dare risultati inaspettati si il fil eXML incluso ha una DTD collegata.

Elenco dei parametri

options: parametri libxml. Disponibile da PHP 5.1.0 e Libxml 2.6.7.

Valori restituiti

Restituisce il numero di XIncludes nel documento.

Esempi

Esempio 1. Esempio di uso di DOMDocument->xinclude()
<?php $xml = <<<EOD <?xml version="1.0" ?> <chapter xmlns:xi="http://www.w3.org/2001/XInclude"> <title>Books of the other guy..</title> <para> <xi:include href="book.xml"> <xi:fallback> <error>xinclude: book.xml not found</error> </xi:fallback> </xi:include> </para> </chapter> EOD; $dom = new DOMDocument; // output formattato $dom->preserveWhiteSpace = false; $dom->formatOutput = true; // carica la stringa XML definita in precedenza $dom->loadXML($xml); // sostituisce gli xincludes $dom->xinclude(); echo $dom->saveXML(); ?>
Il precedente esempio visualizzerà qualcosa simile a:
<?xml version="1.0"?> <chapter xmlns:xi="http://www.w3.org/2001/XInclude"> <title>Books of the other guy..</title> <para> <row xml:base="/home/didou/book.xml"> <entry>The Grapes of Wrath</entry> <entry>John Steinbeck</entry> <entry>en</entry> <entry>0140186409</entry> </row> <row xml:base="/home/didou/book.xml"> <entry>The Pearl</entry> <entry>John Steinbeck</entry> <entry>en</entry> <entry>014017737X</entry> </row> <row xml:base="/home/didou/book.xml"> <entry>Samarcande</entry> <entry>Amine Maalouf</entry> <entry>fr</entry> <entry>2253051209</entry> </row> </para> </chapter>

DOMElement->__construct()

(no version information, might be only in CVS)

DOMElement->__construct() -- Crea un nuovo oggetto DOMElement

Descrizione

class DOMElement {

__construct ( string name [, string value [, string namespaceURI]] )

}

Crea un nuovo oggetto DOMElement. Questo oggetto è in sola lettura. Può essere aggiunto al documento, ma nodi addizionali non possono essere aggiunti a questo, fino a quando il nodo è associatoi al docuemnto. Per creare un nodo modificabile utilizzare DOMDocument->createElement() oppure DOMDocument->createElementNS().

Elenco dei parametri

name: Nome del tag dell'elemento. Quando si passa l'URI di uno spazio dei nomi, il nome dell'elemento può avere un prefisso per essere associato all'URI.
value: Valore dell'elemento.
namespaceURI: URI dello spazio dei nomi, usato per creare l'elemento nello spazio dei nomi indicato.

Esempi

Esempio 1. Creazione di un nuovo DOMElement
<?php $dom = new DOMDocument('1.0', 'iso-8859-1'); $element = $dom->appendChild(new DOMElement('root')); $element_ns = new DOMElement('pr:node1', 'thisvalue', 'http://xyz'); $element->appendChild($element_ns); echo $dom->saveXML(); /* <?xml version="1.0" encoding="iso-8859-1"?> <root><pr:node1 xmlns:pr="http://xyz">thisvalue</pr:node1></root> */ ?>

Vedere anche:

DOMElement->getAttribute()

(no version information, might be only in CVS)

DOMElement->getAttribute() -- Restituisce il valore di un attributo

Descrizione

class DOMElement {

string getAttribute ( string name )

}

Restituisce il valore dell'attributo con nome name per il nodo corrente.

Elenco dei parametri

name: Nome dell'attributo.

Valori restituiti

La funzione restituisce il valore dell'attributo oppure una stringa vuota se non si trova alcun attributo con nome name.

Vedere anche:

DOMElement->setAttribute()

DOMElement->removeAttribute()

DOMElement->getAttributeNode()

(no version information, might be only in CVS)

DOMElement->getAttributeNode() -- Restituisce il nodo attributo

Descrizione

class DOMElement {

DOMAttr getAttributeNode ( string name )

}

Restituisce il nodo attributo con nome name per l'elemento corrente.

Elenco dei parametri

name: Nome dell'attributo.

Valori restituiti

Il nodo attributo.

Vedere anche:

DOMElement->setAttributeNode()

DOMElement->getAttributeNodeNS()

(no version information, might be only in CVS)

DOMElement->getAttributeNodeNS() -- Restituisce un nodo attributo

Descrizione

class DOMElement {

DOMAttr getAttributeNodeNS ( string namespaceURI, string localName )

}

Restituisce il nodo attributo cone nome localName nello spazio dei nomi namespaceURI per il nodo corrente.

Elenco dei parametri

namespaceURI: URI dello spazio dei nomi.
localName: Nome locale.

Valori restituiti

The attribute node.

Vedere anche:

DOMElement->setAttributeNodeNS()

DOMElement->getAttributeNS()

(no version information, might be only in CVS)

DOMElement->getAttributeNS() -- Restituisce il valore di un attributo

Descrizione

class DOMElement {

string getAttributeNS ( string namespaceURI, string localName )

}

Restituisce il valore dell'attributo con nome localName nello spazio dei nomi namespaceURI per il nodo corrente.

Elenco dei parametri

namespaceURI: URI dello spazio dei nomi.
localName: Nome locale.

Valori restituiti

Il valore dell'attributo, oppure una stringa vuota nel caso in cui non si trovi un attributo con i dati localName e namespaceURI.

Vedere anche:

DOMElement->setAttributeNS()

DOMElement->removeAttributeNS()

DOMElement->getElementsByTagName()

(no version information, might be only in CVS)

DOMElement->getElementsByTagName() -- Restituisce gli elementi in base al nome del tag

Descrizione

class DOMElement {

DOMNodeList getElementsByTagName ( string name )

}

Questa funzione restituisce una nuova istanza della classe DOMNodeList contenente gli elementi i cui nomi di tag corrispondono al parametro name, nell'ordine in cui sono incontrati durante l'attraversamento dell'albero.

Elenco dei parametri

name: Il nome del tag. Utilizzare "*" per indicare di restituire tutti gli elementi del documento.

Valori restituiti

Questa funzione crea una nuova istanza della classe DOMNodeList contenente tutti gli elementi trovati.

Vedere anche:

DOMElement->getElementsByTagNameNS()

(no version information, might be only in CVS)

DOMElement->getElementsByTagNameNS() -- Restituisce gli elementi per spazio dei nomi e nome locale

Descrizione

class DOMElement {

DOMNodeList getElementsByTagNameNS ( string namespaceURI, string localName )

}

Questa funzione scarica tutti gli elementi con un dato localName e namespaceURI.

Elenco dei parametri

namespaceURI: URI dello spazio dei nomi.
localName: Nome locale. Utilizzare come nome "*" per restituire tutti gli elementi presenti nell'albero degli elementi.

Valori restituiti

Questa funzione crea una nuova istanza della classe DOMNodeList contenente tutti gli elementi trovati nell'ordine in cui sono incontrati durante l'atttraversamento dell'albero degli elementi.

Vedere anche:

DOMElement->getElementsByTagName()

DOMElement->hasAttribute()

(no version information, might be only in CVS)

DOMElement->hasAttribute() -- Verifica se l'attributo esiste

Descrizione

class DOMElement {

bool hasAttribute ( string name )

}

Indica se l'attributo name esiste come menbro dell'elemento.

Elenco dei parametri

name: Nome dell'attributo.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

DOMElement->getAttribute()

DOMElement->setAttribute()

DOMElement->removeAttribute()

DOMElement->hasAttributeNS()

(no version information, might be only in CVS)

DOMElement->hasAttributeNS() -- Verifica se esiste l'attributo

Descrizione

class DOMElement {

bool hasAttributeNS ( string namespaceURI, string localName )

}

Indica se l'attributo nello spazio dei nomi namespaceURI con nome localName esiste come membro dell'elemento.

Elenco dei parametri

namespaceURI: URI dello spazio dei nomi.
localName: Nome locale.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

DOMElement->getAttributeNS()

DOMElement->setAttributeNS()

DOMElement->removeAttributeNS()

DOMElement->removeAttribute()

(no version information, might be only in CVS)

DOMElement->removeAttribute() -- Rimuove l'attributo

Descrizione

class DOMElement {

bool removeAttribute ( string name )

}

Rimuove l'attributo name dall'elemento.

Elenco dei parametri

name: Nome dell'attributo.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Eccezioni

DOM_NO_MODIFICATION_ALLOWED_ERR: Generato se il nodo non può essere modificato (in sola lettura).

Vedere anche:

DOMElement->getAttribute()

DOMElement->setAttribute()

DOMElement->removeAttributeNode()

(no version information, might be only in CVS)

DOMElement->removeAttributeNode() -- Rimuove gli attributi

Descrizione

class DOMElement {

bool removeAttributeNode ( DOMAttr oldnode )

}

Rimuove l'attributo oldnode dall'elemento.

Elenco dei parametri

oldnode: Nodo attributo.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Eccezioni

DOM_NO_MODIFICATION_ALLOWED_ERR: Generato se il nodo è in sola lettura.
DOM_NOT_FOUND_ERROR: Generato se oldnode non è un attributo dell'elemento.

Vedere anche:

DOMElement->getAttributeNode()

DOMElement->setAttributeNode()

DOMElement->removeAttributeNS()

(no version information, might be only in CVS)

DOMElement->removeAttributeNS() -- Rimuove gli attributi

Descrizione

class DOMElement {

bool removeAttributeNS ( string namespaceURI, string localName )

}

Rimuove l'attributo localName nello spazio dei nomi namespaceURI dall'elemento.

Elenco dei parametri

namespaceURI: URI dello spazio dei nomi.
localName: Nome locale.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Eccezioni

DOM_NO_MODIFICATION_ALLOWED_ERR: Generato se il nodo è in sola lettura.

Vedere anche:

DOMElement->getAttributeNS()

DOMElement->setAttributeNS()

DOMElement->setAttribute()

(no version information, might be only in CVS)

DOMElement->setAttribute() -- Aggiunge un nuovo attributo

Descrizione

class DOMElement {

bool setAttribute ( string name, string value )

}

Imposta l'attributo con nome name al dato valore. Se l'attributo non esiste lo crea.

Elenco dei parametri

name: Nome dell'attributo.
value: Valore dell'attributo.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Eccezioni

DOM_NO_MODIFICATION_ALLOWED_ERR: Generato se il nodo è in sola lettura.

Esempi

Esempio 1. Setting an attribute
<?php $doc = new DOMDocument("1.0"); $node = $doc->createElement("para"); $newnode = $doc->appendChild($node); $newnode->setAttribute("align", "left"); ?>

Vedere anche:

DOMElement->getAttribute()

DOMElement->removeAttribute()

DOMElement->setAttributeNode()

(no version information, might be only in CVS)

DOMElement->setAttributeNode() -- Aggiunge un nuovo nodo attributo all'elemento

Descrizione

class DOMElement {

DOMAttr setAttributeNode ( DOMAttr attr )

}

Aggiunge un nuovo nodo attributo attr all'elemento.

Elenco dei parametri

attr: Nodo attributo.

Valori restituiti

Restituisce il vecchio nodo se questo viene sostituito oppure NULL.

Eccezioni

DOM_NO_MODIFICATION_ALLOWED_ERR: Generato se il nodo è in sola lettura.

Vedere anche:

DOMElement->getAttributeNode()

DOMElement->setAttributeNodeNS()

(no version information, might be only in CVS)

DOMElement->setAttributeNodeNS() -- Aggiunge un nuovo nodo attributo all'elemento

Descrizione

class DOMElement {

DOMAttr setAttributeNodeNS ( DOMAttr attr )

}

Aggiunge un nuovo nodo attr all'elemento.

Elenco dei parametri

name: Nodo attributo.

Valori restituiti

Restituisce il vecchio nodo se l'attributo viene sostituito.

Eccezioni

DOM_NO_MODIFICATION_ALLOWED_ERR: Generato se il nodo è in sola lettura.

Vedere anche:

DOMElement->getAttributeNodeNS()

DOMElement->setAttributeNS()

(no version information, might be only in CVS)

DOMElement->setAttributeNS() -- Aggiunge un nuovo attributo

Descrizione

class DOMElement {

void setAttributeNS ( string namespaceURI, string qualifiedName, string value )

}

Imposta un attributo di nome name nello spazio dei nomi namespaceURI al valore dato. Se l'attributo non esiste viene creato.

Elenco dei parametri

namespaceURI: URI dello spazio dei nomi.
qualifiedName: Nome qualificato dell'attributo, nella forma prefisso:nometag.
value: Valore dell'attributo.

Valori restituiti

No value is returned.

Eccezioni

DOM_NO_MODIFICATION_ALLOWED_ERR: Generato se il nodo è in sola lettura.
DOM_NAMESPACE_ERR: Generato se qualifiedName è un nome qualificato malformato, oppure se qualifiedName ha un prefisso, ma namespaceURI è NULL.

Vedere anche:

DOMElement->getAttributeNS()

DOMElement->removeAttributeNS()

DOMAttr->__construct()

(no version information, might be only in CVS)

DOMAttr->__construct() -- Crea un nuovo oggetto DOMEntityReference

Descrizione

class DOMEntityReference {

__construct ( string name )

}

Crea un nuovo oggetto DOMEntityReference.

Elenco dei parametri

name: Nome dell'entità

Esempi

Esempio 1. Creazione di un nuovo DOMEntityReference
<?php $dom = new DOMDocument('1.0', 'iso-8859-1'); $element = $dom->appendChild(new DOMElement('root')); $entity = $element->appendChild(new DOMEntityReference('nbsp')); echo $dom->saveXML(); /* <?xml version="1.0" encoding="iso-8859-1"?><root> </root> */ ?>

Vedere anche:

DOMDocument->__construct()

DOMImplementation->__construct()

(no version information, might be only in CVS)

DOMImplementation->__construct() -- Crea un nuovo oggetto DOMImplementation

Descrizione

class DOMImplementation {

__construct ( (void); )

}

Crea un nuovo oggetto DOMImplementation.

DOMImplementation->createDocument()

(no version information, might be only in CVS)

DOMImplementation->createDocument() -- Crea un oggetto DOMDocument del tipo indicato con il suo elemento documento

Descrizione

class DOMImplementation {

DOMDocument createDocument ( [string namespaceURI [, string qualifiedName [, DOMDocumentType doctype]]] )

}

Crea un oggetto DOMDocument del tipo specificato, con l'elemento documento.

Elenco dei parametri

namespaceURI: URI dello spazio dei nomi dell'elemento documento da creare.
qualifiedName: Nome qualificato dell'elemento documento da creare.
doctype: Tipo del documento da creare oppure NULL.

Valori restituiti

Restituisce un nuovo oggetto DOMDocument. Se namespaceURI, qualifiedName, e doctype sono a null, l'oggetto DOMDocument restituito è vuoto, cioè privo dell'elemento documento.

Eccezioni

DOM_WRONG_DOCUMENT_ERR: Generato se doctype è già utilizzato in un documento differente oppure è stato creato con una differente implementazione.
DOM_NAMESPACE_ERR: Generato se esiste un errore nello spazio dei nomi indicato da namespaceURI e qualifiedName.

Vedere anche:

DOMImplementation->createDocumentType()

(no version information, might be only in CVS)

DOMImplementation->createDocumentType() -- Crea un oggetto DOMDocumentType vuoto

Descrizione

class DOMImplementation {

DOMDocumentType createDocumentType ( [string qualifiedName [, string publicId [, string systemId]]] )

}

Crea un oggetto DOMDocumentType vuoto. Le dichiarazioni delle entità e notazioni non sono disponibili. L'espansione delle entità e gli attributi di default non sono presenti.

Elenco dei parametri

qualifiedName: Nome qualificato del tipo documento da creare.
publicId: Identificatore pubblico esterno.
systemId: Identificatore di sistema esterno.

Valori restituiti

Un nuovo nodo DOMDocumentType con il suo ownerDocument impostato a NULL.

Esempi

Esempio 1. Creazione di un documento con una DTD collegata
<?php // Istanza della classe DOMImplementation $imp = new DOMImplementation; // Crea un'istanza di DOMDocumentType $dtd = $imp->createDocumentType('graph', '', 'graph.dtd'); // Crea un'istanza di DOMDocument $dom = $imp->createDocument("", "", $dtd); // Imposta altre opzioni $dom->encoding = 'UTF-8'; $dom->standalone = false; // Crea un elemento vuoto $element = $dom->createElement('graph'); // Aggiunge l'elemento $dom->appendChild($element); // Recupera e scrive il documento echo $dom->saveXML(); ?>
Il precedente esempio visualizzerà:
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <!DOCTYPE graph SYSTEM "graph.dtd"> <graph/>

Eccezioni

DOM_NAMESPACE_ERR: Generato se vi è un errore nello spazio dei nomi indicato da qualifiedName.

Vedere anche:

DOMImplementation->createDocument()

DOMImplementation->hasFeature()

(no version information, might be only in CVS)

DOMImplementation->hasFeature() -- Verifica se l'implementazione DOM ha una specifica caratteristica

Descrizione

class DOMImplementation {

bool hasFeature ( string feature, string version )

}

Verifica se l'implementazione DOM ha una specifica feature.

Si può avere l'eleneco di tutte le caratteristiche alla sezione Conformance delle specifiche DOM.

Elenco dei parametri

feature: Caratteristica da verificare.
version: Numero di versione della feature da verificare. Nel livello 2 questo parametro può valere 2.0 o 1.0.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 1. Verifica dell'implementazione DOM

<?php

$features = array(
  'Core'           => 'Core module',
  'XML'            => 'XML module',
  'HTML'           => 'HTML module',
  'Views'          => 'Views module',
  'Stylesheets'    => 'Style Sheets module',
  'CSS'            => 'CSS module',
  'CSS2'           => 'CSS2 module',
  'Events'         => 'Events module',
  'UIEvents'       => 'User interface Events module',
  'MouseEvents'    => 'Mouse Events module',
  'MutationEvents' => 'Mutation Events module',
  'HTMLEvents'     => 'HTML Events module',
  'Range'          => 'Range module',
  'Traversal'      => 'Traversal module'
);
               
foreach ($features as $key => $name) {
  if (DOMImplementation::hasFeature($key, '2.0')) {
    echo "Has feature $name\n";
  } else {
    echo "Missing feature $name\n";
  }
}

?>

Vedere anche:

DOMNode->isSupported()

DOMNamedNodeMap->getNamedItem()

(no version information, might be only in CVS)

DOMNamedNodeMap->getNamedItem() -- Recupera un nodo indicandone il nome

Descrizione

class DOMNamedNodeMap {

DOMNode getNamedItem ( string name )

}

Recupera il nodo indicato da nodeName.

Elenco dei parametri

name: Il nome del nodo da cercare.

Valori restituiti

Il nodo (di qualsiasi tipo) con il nome richiesto, oppure NULL se non viene trovato.

Vedere anche:

DOMNamedNodeMap->getNamedItemNS()

(no version information, might be only in CVS)

DOMNamedNodeMap->getNamedItemNS() -- Recupera un nodo indicando il nome locale e l'URI dello spazio dei nomi

Descrizione

class DOMNamedNodeMap {

DOMNode getNamedItemNS ( string namespaceURI, string localName )

}

Recupera il nodo indicato da localName e namespaceURI.

Elenco dei parametri

namespaceURI: URI dello spazio dei nomi del nodo da cercare
localName: Nome locale del nodo da cercare.

Valori restituiti

Un nodo (di qualsiasi tipo) con il nome locale ed l'URI dello spazio dei nomi richiesti, oppure NULL se non viene trovato nulla.

Vedere anche:

DOMNamedNodeMap->getNamedItem()

DOMNamedNodeMap->item()

(no version information, might be only in CVS)

DOMNamedNodeMap->item() -- Recupera un nodo tramite il suo indice

Descrizione

class DOMNamedNodeMap {

DOMNode item ( int index )

}

Recupera un nodo tramite l'indice index all'interno dell'oggetto DOMNamedNodeMap.

Elenco dei parametri

index: Indice all'interno della tabella.

Valori restituiti

Il nodo alla posizione indexnella tabella, oppure NULL se non si tratta di un indice valido (maggiore o uguale al numero dei nodi in questa tabella).

DOMNode->appendChild()

(no version information, might be only in CVS)

DOMNode->appendChild() -- Aggiunge un nuovo nodo figlio alla fine dei nodi figli

Descrizione

class DOMNode {

DOMNode appendChild ( DOMNode newnode )

}

Questa funzione accoda un nodo figlio ad una lista esistente di nodi figlio oppure crea una nuova lista. Il nodo figlio può essere creato, ad esempio, con DOMDocument->createElement(), DOMDocument->createTextNode() ecc. oppure semplicemente utilizzando un'altro nodo.

Elenco dei parametri

newnode: Il nodo figlio da aggiungere.

Valori restituiti

Il nodo aggiunto.

Eccezioni

DOM_NO_MODIFICATION_ALLOWED_ERR: Generato se questo nodo è in sola lettura, oppure se il nodo genitore del nodo da inserire è in sola lettura.
DOM_HIERARCHY_REQUEST_ERR: Generato se questo nodo è del tipo che non ammette figli del tipo di newnode, oppure se il nodo da aggiungere è uno dei genitori del nodi o di se stesso.
DOM_WRONG_DOCUMENT_ERR: Generato se newnode è stato creato in un documento differente rispetto al nodo che crea questo.

Esempi

Nel seguente esempio si aggiunge un nuovo nodo elemento ad un documento.
Esempio 1. Aggiunta di un nodo figlio
<?php $doc = new DOMDocument; $node = $doc->createElement("para"); $newnode = $doc->appendChild($node); echo $doc->saveXML(); ?>

Vedere anche:

DOMNode->removeChild()

DOMNode->replaceChild()

DOMNode->cloneNode()

(no version information, might be only in CVS)

DOMNode->cloneNode() -- Clona un nodo

Descrizione

class DOMNode {

DOMNode cloneNode ( [bool deep] )

}

Crea una copia di un nodo.

Elenco dei parametri

deep: Indica se occorre copiare tutti i nodi sottostanti. Questo parametro, opzionale, ha come default FALSE.

Valori restituiti

Il nodo clonato.

DOMNode->hasAttributes()

(no version information, might be only in CVS)

DOMNode->hasAttributes() -- Verifica se un nodo ha degli attributi

Descrizione

class DOMNode {

bool hasAttributes ( void )

}

Questa funzione verifica se un nodo ha degli attributi. Il nodo verificato deve essere di tipo XML_ELEMENT_NODE.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

DOMNode->hasChildNodes()

(no version information, might be only in CVS)

DOMNode->hasChildNodes() -- Verifica se un nodo ha nodi figli

Descrizione

class DOMNode {

bool hasChildNodes ( void )

}

Questa funzione verifica se un nodo ha nodi figli.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

DOMNode->hasAttributes()

DOMNode->insertBefore()

(no version information, might be only in CVS)

DOMNode->insertBefore() -- Aggiunge un nuovo nodo figlio prima del riferimento

Descrizione

class DOMNode {

DOMNode insertBefore ( DOMNode newnode [, DOMNode refnode] )

}

Questa funzione inserisce un nuovo nodo prima del nodo di riferimento. Se si prevede di fare ulteriori aggiunte al nodo aggiunto, utilizzare il nodo restituito.

Elenco dei parametri

newnode: Il nuovo nodo.
refnode: Nodo di riferimento. Se non viene fornito, newnode viene accodato ai nodi figli.

Valori restituiti

Il nodo inserito.

Eccezioni

DOM_NO_MODIFICATION_ALLOWED_ERR: Generato se il nodo è in sola lettura o se il precedente nodo padre del nodo da aggiungere è in sola lettura.
DOM_HIERARCHY_REQUEST_ERR: Generato se questo nodo è di un tipo che non permette l'aggiunta di nodi figli del tipo di newnode, o se il nodo da aggiungere è uno dei genitori di questo nodo, oppure se si tratta proprio di questo nodo.
DOM_WRONG_DOCUMENT_ERR: Generato se newnode è stato creato in un docuemnto differente rispetto al documento in cui è sttao creato questo nodo.
DOM_NOT_FOUND: Generato se refnode non è un nodo figlio di questo nodo.

DOMNode->isSameNode()

(no version information, might be only in CVS)

DOMNode->isSameNode() -- Indica se due nodi sono il medesimo nodo

Descrizione

class DOMNode {

bool isSameNode ( DOMNode node )

}

Questa funzione indica se due nodi sono il medesimo nodo. Il confronto NON è basato sul contenuto.

Elenco dei parametri

node: Il nodo confrontato.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

DOMNode->isSupported()

(no version information, might be only in CVS)

DOMNode->isSupported() -- Verifica se una caratteristica è supportata dalla versione indicata

Descrizione

class DOMNode {

bool isSupported ( string feature, string version )

}

Verifica se una feature è supportata dalla version indicata.

Elenco dei parametri

feature: Caratteristica da verificare. Vedere l'esempio di DOMImplementation->hasFeature() per avere l'elenco delle caratteristiche.
version: Numero di versione della feature da verificare.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

DOMImplementation->hasFeature()

DOMNode->lookupNamespaceURI()

(no version information, might be only in CVS)

DOMNode->lookupNamespaceURI() -- Restituisce l'URI dello spazio dei nomi in base al prefisso

Descrizione

class DOMNode {

string lookupNamespaceURI ( string prefix )

}

Restituisce l'URI dello spazio dei nomi del nodo in base al prefisso prefix.

Elenco dei parametri

prefix: Prefisso dello spazio dei nomi

Valori restituiti

URI dello spazio dei nomi del nodo.

Vedere anche:

DOMNode->lookupPrefix()

(no version information, might be only in CVS)

DOMNode->lookupPrefix() -- Resituisce il prefisso dello spazio dei nomi in base all'URI dello spazio dei nomi

Descrizione

class DOMNode {

string lookupPrefix ( string namespaceURI )

}

Resituisce il prefisso dello spazio dei nomi in base all'URI dello spazio dei nomi.

Elenco dei parametri

namespaceURI: URI dello spazio dei nomi.

Valori restituiti

Il prefisso dello spazio dei nomi.

Vedere anche:

DOMNode->lookupNamespaceURI()

DOMNode->normalize()

(no version information, might be only in CVS)

DOMNode->normalize() -- Normalizza un nodo

Descrizione

class DOMNode {

void normalize ( void )

}

Normalizza il nodo.

Valori restituiti

No value is returned.

Vedere anche:

DOMDocument->normalize()

DOMNode->removeChild()

(no version information, might be only in CVS)

DOMNode->removeChild() -- Rimuove un nodo figlio dalla lista dei nodi figli

Descrizione

class DOMNode {

DOMNode removeChild ( DOMNode oldnode )

}

Questa funzione rimuove un nodo figlio dalla lista dei nodi figli.

Elenco dei parametri

oldnode: Il nodo rimosso.

Valori restituiti

Se si riesce a rimuovere il nodo figlio, la funzione restituisce il vecchio nodo figlio.

Eccezioni

DOM_NO_MODIFICATION_ALLOWED_ERR: Generato se il nodo è in sola lettura.
DOM_NOT_FOUND: Generato se oldnode non è un figlio di questo nodo.

Esempi

Nel seguente esempio si rimuoverà il nodo 'chapter' dal nostro documento XML.
Esempio 1. Rimozione di un nodo figlio
<?php $doc = new DOMDocument; $doc->load('book.xml'); $book = $doc->documentElement; // Cerchiamo il nodo e lo rimuoviamo $chapter = $book->getElementsByTagName('chapter')->item(0); $oldchapter = $book->removeChild($chapter); echo $doc->saveXML(); ?>
Il precedente esempio visualizzerà:
<?xml version="1.0" encoding="iso-8859-1"?> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> <book id="listing"> <title>My lists</title> </book>

Vedere anche:

DOMNode->replaceChild()

(no version information, might be only in CVS)

DOMNode->replaceChild() -- Sostituisce un nodo figlio

Descrizione

class DOMNode {

DOMNode replaceChild ( DOMNode newnode, DOMNode oldnode )

}

Questa funzione sostituisce il nodo figlio oldnode con il nuovo nodo fornito. Se il nuovo nodo è già un nodo figlio, questo non verrà inserito una seconda volta. Se la sostituzione ha avuto successo, la funzione restituisce il vecchio nodo.

Elenco dei parametri

newnode: Il nuovo nodo. Deve essere membro del docuemnto di destinazione, ad esempio creato da uno dei metodi DOMDocument->createXXX() oppure importato nel documento con DOMDocument->importNode().
oldnode: Il vecchio nodo.

Valori restituiti

Il vecchio nodo oppure FALSE in caso di errore.

Eccezioni

DOM_NO_MODIFICATION_ALLOWED_ERR: Generato se questo nodo è in sola lettura oppure se il precdente padre del nodo da inserire è in sola lettura.
DOM_HIERARCHY_REQUEST_ERR: Generato se il nodo è di un tipo che non ammette nodi figli del tipo di newnode, oppure se il nodo da inserire è uno dei padri del nodo, oppure se è il nodo stesso.
DOM_WRONG_DOCUMENT_ERR: Generato se newnode è stato creato in un docuemnto differente rispetto al documento in cui è stato creato il nodo.
DOM_NOT_FOUND: Generato se oldnode non è figlio del nodo.

Vedere anche:

DOMNode->removeChild()

DOMNodelist->item()

(no version information, might be only in CVS)

DOMNodelist->item() -- Recupera il nodo indicato dall'indice

Descrizione

class DOMNodeList {

DOMNode item ( int index )

}

Trova il nodo indicato dall'indice index all'interno di un oggetto DOMNodeList.

Suggerimento: Se occorre conoscere il numero di nodi di una collezzione utilizzare la prorpietà length dell'oggetto DOMNodeList.

Elenco dei parametri

index: Indice del nodo nella collezione.

Valori restituiti

Il nodo alla posizione index in DOMNodeList, oppure NULL se non è un indice valido.

Esempi

Esempio 1. Attraversamento di tutti gli elementi di una tabella
<?php $doc = new DOMDocument; $doc->load('book.xml'); $items = $doc->getElementsByTagName('entry'); for ($i = 0; $i < $items->length; $i++) { echo $items->item($i)->nodeValue . "\n"; } ?>
Oppure si può utilizzare foreach, che è molto pratico:
<?php foreach ($items as $item) { echo $item->nodeValue . "\n"; } ?>
Il precedente esempio visualizzerà:
Title Author Language ISBN The Grapes of Wrath John Steinbeck en 0140186409 The Pearl John Steinbeck en 014017737X Samarcande Amine Maalouf fr 2253051209

DOMProcessingInstruction->__construct()

(no version information, might be only in CVS)

DOMProcessingInstruction->__construct() -- Crea un nuovo oggetto DOMProcessingInstruction

Descrizione

class DOMProcessingInstruction {

__construct ( string name [, string value] )

}

Crea un nuovo oggetto DOMProcessingInstruction. Questo oggetto è in sola lettura. Può essere aggiunto al documento, ma non possono essere inseriti nodi aggiuntivi fino a quando il nodo è associato al documento. Per creare un nodo modificabile utilizzare DOMDocument->createProcessingInstruction().

Elenco dei parametri

name: Nome del tag dell'istruzione di processamento.
value: Valore dell'istruzione di processamento.

Esempi

Esempio 1. Creazione di un nuovo DOMProcessingInstruction
<?php $dom = new DOMDocument('1.0', 'UTF-8'); $html = $dom->appendChild(new DOMElement('html')); $body = $html->appendChild(new DOMElement('body')); $pinode = new DOMProcessingInstruction('php', 'echo "Hello World"; '); $body->appendChild($pinode); echo $dom->saveXML(); /* <?xml version="1.0" encoding="iso-8859-1"?> <html><body><?php echo "Hello World"; ?></body></html> */ ?>

Vedere anche:

DOMText->__construct()

(no version information, might be only in CVS)

DOMText->__construct() -- Crea un nuovo oggetto DOMText

Descrizione

class DOMText {

__construct ( [string value] )

}

Crea un nuovo oggetto DOMText.

Elenco dei parametri

value: Valore del nodo di testo. Se non fornito, sarà creato un nodo con il testo vuoto.

Esempi

Esempio 1. Creazione di un nuovo DOMText
<?php $dom = new DOMDocument('1.0', 'iso-8859-1'); $element = $dom->appendChild(new DOMElement('root')); $text = $element->appendChild(new DOMText('root value')); echo $dom->saveXML(); /* <?xml version="1.0" encoding="iso-8859-1"?><root>root value</root> */ ?>

Vedere anche:

DOMText->isWhitespaceInElementContent()

(no version information, might be only in CVS)

DOMText->isWhitespaceInElementContent() -- Indica se questo nodo di testo contiene spazi

Descrizione

class DOMText {

bool isWhitespaceInElementContent ( void )

}

Indica se questo nodo di testo contiene spazi. Si determina se un nodo di testo contiene spazi durante la fase di caricamento del documento.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

DOMText->splitText()

(no version information, might be only in CVS)

DOMText->splitText() -- Spezza il nodo in due all'offset specificato

Descrizione

class DOMText {

DOMText splitText ( int offset )

}

Spezza questo nodo in due all'offset indicato, mantenendo entrambi nell'albero come nodi fratelli.

Dopo la divisione, questo nodo conterrà tutto il testo fino a offset. Se il nodo originale ha un nodo genitore, allora il nuovo nodo sarà inserito come successivo al nodo originale. Nel caso in cui offset sia uguale alla lunghezza del nodo, il nuovo nodo non conterrà dati.

Elenco dei parametri

offset: Offset al quale dividere, a partire da 0.

Valori restituiti

Il nuovo nodo, del medesimo tipo, avrà tutto il contenuto a partire da offset.

DOMXPath->__construct()

(no version information, might be only in CVS)

DOMXPath->__construct() -- Crea un nuovo oggetto DOMXPath

Descrizione

class DOMXPath {

__construct ( DOMDocument doc )

}

Crea un nuovo oggetto DOMXPath.

Elenco dei parametri

doc: L'oggetto DOMDocument associato a DOMXPath.

DOMXPath->evaluate()

(no version information, might be only in CVS)

DOMXPath->evaluate() -- Valuta l'espressione XPath data e restituisce un risultato se possibile

Descrizione

class DOMXPath {

mixed evaluate ( string expression [, DOMNode contextnode] )

}

Esegue l'espressione XPath data e restituisce un risultato se possibile

Elenco dei parametri

expression: L'espressione XPath da eseguire.
contextnode: Il parametro opzinale contextnode serve per indicare di eseguire query XPath relative. Per default le query sono relative all'elemento radice.

Valori restituiti

Restituisce un risultato oppure un oggetto DOMNodeList contenente tutti i nodi che soddisfano la query XPath .

Esempi

Esempio 1. Ottenere il numero dei libri inglesi
<?php $doc = new DOMDocument; $doc->load('book.xml'); $xpath = new DOMXPath($doc); $tbody = $doc->getElementsByTagName('tbody')->item(0); // query relativa ai nodi tbody $query = 'count(row/entry[. = "en"])'; $entries = $xpath->evaluate($query, $tbody); echo "There are $entries english books\n"; ?>
Il precedente esempio visualizzerà:
There are 2 english books

Vedere anche:

DOMXPath->query()

(no version information, might be only in CVS)

DOMXPath->query() -- Valuta l'espressione XPath

Descrizione

class DOMXPath {

DOMNodeList query ( string expression [, DOMNode contextnode] )

}

Esegue la query XPath data.

Elenco dei parametri

expression: La query XPath da eseguire.
contextnode: Il parametro opzinale contextnode serve per indicare di eseguire query XPath relative. Per default le query sono relative all'elemento radice.

Valori restituiti

Restituisce un oggetto DOMNodeList contenente tutti i nodi che soddisfano la condizione expression. Qualsiasi espressione che non restituisce nodi creerà un DOMNodeList vuoto.

Esempi

Esempio 1. Ottenere il numero dei libri inglesi
<?php $doc = new DOMDocument; // We don't want to bother with white spaces $doc->preserveWhiteSpace = false; $doc->Load('book.xml'); $xpath = new DOMXPath($doc); // Partiamo dell'elemento radice $query = '//book/chapter/para/informaltable/tgroup/tbody/row/entry[. = "en"]'; $entries = $xpath->query($query); foreach ($entries as $entry) { echo "Found {$entry->previousSibling->previousSibling->nodeValue}," . " by {$entry->previousSibling->nodeValue}\n"; } ?>
Il precedente esempio visualizzerà:
Found The Grapes of Wrath, by John Steinbeck Found The Pearl, by John Steinbeck
Possiamo utilizzare il parametro contextnode per ridurre l'espressione:
<?php $doc = new DOMDocument; $doc->preserveWhiteSpace = false; $doc->load('book.xml'); $xpath = new DOMXPath($doc); $tbody = $doc->getElementsByTagName('tbody')->item(0); // query relativa ai nodi tbody $query = 'row/entry[. = "en"]'; $entries = $xpath->query($query, $tbody); foreach ($entries as $entry) { echo "Found {$entry->previousSibling->previousSibling->nodeValue}," . " by {$entry->previousSibling->nodeValue}\n"; } ?>

Vedere anche:

DOMXPath->evaluate()

DOMXPath->registerNamespace()

(no version information, might be only in CVS)

DOMXPath->registerNamespace() -- Registra lo spazio dei nomi nell'oggetto DOMXpath

Descrizione

class DOMXPath {

bool registerNamespace ( string prefix, string namespaceURI )

}

Registra lo spazio dei nomi namespaceURI e prefix nell'oggetto DOMXpath.

Elenco dei parametri

prefix: Il prefisso.
namespaceURI: URI dello spazio dei nomi.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

dom_import_simplexml

(PHP 5)

dom_import_simplexml -- Ottiene un'oggetto DOMElement da un'oggetto SimpleXMLElement

Descrizione

DOMElement dom_import_simplexml ( SimpleXMLElement node )

Questa funzione prende il nodo node della classe SimpleXML e lo converte in un nodo DOMElement. Questo nuovo oggetto può essere utilizzato come nodo DOMElement nativo.

Elenco dei parametri

node: Il nodo SimpleXMLElement.

Valori restituiti

Il nodo DOMElement aggiunto oppure FALSE in caso di errore.

Esempi

Esempio 1. Importare SimpleXML nel DOM con dom_import_simplexml()

<?php

$sxe = simplexml_load_string('<books><book><title>blah</title></book></books>');

if ($sxe === false) {
    echo 'Error while parsing the document';
    exit;
}

$dom_sxe = dom_import_simplexml($sxe);
if (!$dom_sxe) {
    echo 'Error while converting XML';
    exit;
}

$dom = new DOMDocument('1.0');
$dom_sxe = $dom->importNode($dom_sxe, true);
$dom_sxe = $dom->appendChild($dom_sxe);

echo $dom->saveXML();

?>

Vedere anche:

simplexml_import_dom()

XXXI. Funzioni DOM XML

Introduzione

Nella versione 4.3.0 di PHP l'estensione DOM XML è stata rivista in modo da fornire una migliore adesione allo standard DOM. Il modulo contiene ancora diverse vecchie funzioni, ma non dovrebbero essere più usate. Specialmente quelle funzioni non orientate agli oggetti.

Questo modulo permette di operare con un documento XML utilizzando API DOM. Inoltre viene fornita una funzione, domxml_xmltree(), per convertire l'intero documento XML in un albero di oggetti PHP. Attualmente questo albero dovrebbe essere considerato di sola lettura, è possibile modificarlo, ma questa operazione non avrebbe senso dato che la funzione DomDocument_dump_mem() non può essere applicata all'albero. Pertanto se si desidera leggere un file XML e scriverne una versione modificata, occorre utilizzare le funzioni DomDocument_create_element(), DomDocument_create_text_node(), set_attribute(), ecc. ed infine DomDocument_dump_mem().

Nota: Questo modulo è stato spostato nel repository PECL e non sarà più rilascio con il PHP dalla versione 5.0.0.

Nota: Questo modulo non è più considerato sperimentale. Tuttavia non sarà rilasciato con PHP 5, e sarà solo distribuito con PHP 4. Se si ha bisogno del supporto DOM XML in PHP 5, si può utilizzare il modulo DOM. Questa estensione domxml non è compatibile con DOM.

Requisiti

Questo modulo utilizza la libreria GNOME XML library. Fare il download ed installare questa libreria. Occorre avere almeno la libxml-2.4.14. Per potere utilizzare le caratteristiche previste nel DOM XSLT occorre utilizzare libxslt library ed EXSLT enhancements da http://www.exslt.org/. Scaricare ed installare queste librerie se si prevede di utilizzare la funzioni avanzate di XSLT. Occorre almeno la versione libxslt-1.0.18.

Installazione

In PHP 4 this PECL extensions source can be found in the ext/ directory within the PHP source or at the PECL link above. Questo modulo è disponibile soltanto se il PHP è stato configurato con --with-dom=[DIR]. Aggiungere --with-dom-xslt[=DIR] per includere il supporto al DOM XSLT support. DIR indica la directory in cui è installato libxslt. Aggiungere --with-dom-exslt[=DIR] per includere il supporto al DOM EXSLT, dove DIR indica la directory in cui è installato libexslt.

Gli utenti Windows devono abilitare php_domxml.dll dal php.ini per potere utilizzare queste funzioni. In PHP 4 this DLL resides in the extensions/ directory within the PHP Windows binaries download. You may download this PECL extension DLL from the PHP Downloads page or at http://snaps.php.net/. Inoltre, per potere utilizzare queste funzioni, occorre che una DLL aggiuntiva sia presente nella PATH del sistema. In PHP 4 questa DLL si trova nella directory dlls/. Il suo nome: Per PHP <= 4.2.0, è libxml2.dll. Per PHP >= 4.3.0, è iconv.dll. E dal PHP 5.0.0 iconv è compilata nell'eseguibile PHP per Windows, percui non vi è più bisogno di dll aggiuntive.

Funzioni deprecate

Esistono alcune funzioni che non rientrano nello standard DOM e quindi non dovrebbero essere più utilizzate come evidenziato nella tabella seguente. La funzione DomNode_append_child() ha modificato il suo comportamento. Attualmente aggiunge un figlio e non un elemento fratello. Se ciò crea problemi alle applicazioni si può usare la funzione non DOM

Tabella 1. Funzioni deprecate e loro sostituti

Vecchia funzione	Nuova funzione
xmldoc	domxml_open_mem()
xmldocfile	domxml_open_file()
domxml_new_xmldoc	domxml_new_doc()
domxml_dump_mem	DomDocument_dump_mem()
domxml_dump_mem_file	DomDocument_dump_file()
DomDocument_dump_mem_file	DomDocument_dump_file()
DomDocument_add_root	DomDocument_create_element() seguita da DomNode_append_child()
DomDocument_dtd	DomDocument_doctype()
DomDocument_root	DomDocument_document_element()
DomDocument_children	DomNode_child_nodes()
DomDocument_imported_node	Nessun sostituto.
DomNode_add_child	Creare un nuovo nodo con, ad esempio, DomDocument_create_element() e aggiungere il figlio con DomNode_append_child().
DomNode_children	DomNode_child_nodes()
DomNode_parent	DomNode_parent_node()
DomNode_new_child	Creare un nuovo nodo con, ad esempio, DomDocument_create_element() e aggiungere il figlio con DomNode_append_child().
DomNode_get_content	Il contenuto è semplicemente un nodo di testo ed è accessibile tramite DomNode_child_nodes().
DomNode_set_content	Il contenuto è semplicemente un nodo di testo e può essere aggiunto con DomNode_append_child().

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

Tabella 2. Costanti XML

Costante	Valore	Descrizione
`XML_ELEMENT_NODE` (integer)	1	Il nodo è un elemento
`XML_ATTRIBUTE_NODE` (integer)	2	Il nodo è un attributo
`XML_TEXT_NODE` (integer)	3	Il nodo è un segmento di testo
`XML_CDATA_SECTION_NODE` (integer)	4
`XML_ENTITY_REF_NODE` (integer)	5
`XML_ENTITY_NODE` (integer)	6	Il nodo è un'entità come, ad esempio,
`XML_PI_NODE` (integer)	7	Il nodo è una istruzione di processamento
`XML_COMMENT_NODE` (integer)	8	Il nodo è un commento
`XML_DOCUMENT_NODE` (integer)	9	Il nodo è un documento
`XML_DOCUMENT_TYPE_NODE` (integer)	10
`XML_DOCUMENT_FRAG_NODE` (integer)	11
`XML_NOTATION_NODE` (integer)	12
`XML_GLOBAL_NAMESPACE` (integer)	1
`XML_LOCAL_NAMESPACE` (integer)	2
`XML_HTML_DOCUMENT_NODE` (integer)
`XML_DTD_NODE` (integer)
`XML_ELEMENT_DECL_NODE` (integer)
`XML_ATTRIBUTE_DECL_NODE` (integer)
`XML_ENTITY_DECL_NODE` (integer)
`XML_NAMESPACE_DECL_NODE` (integer)
`XML_ATTRIBUTE_CDATA` (integer)
`XML_ATTRIBUTE_ID` (integer)
`XML_ATTRIBUTE_IDREF` (integer)
`XML_ATTRIBUTE_IDREFS` (integer)
`XML_ATTRIBUTE_ENTITY` (integer)
`XML_ATTRIBUTE_NMTOKEN` (integer)
`XML_ATTRIBUTE_NMTOKENS` (integer)
`XML_ATTRIBUTE_ENUMERATION` (integer)
`XML_ATTRIBUTE_NOTATION` (integer)
`XPATH_UNDEFINED` (integer)
`XPATH_NODESET` (integer)
`XPATH_BOOLEAN` (integer)
`XPATH_NUMBER` (integer)
`XPATH_STRING` (integer)
`XPATH_POINT` (integer)
`XPATH_RANGE` (integer)
`XPATH_LOCATIONSET` (integer)
`XPATH_USERS` (integer)
`XPATH_NUMBER` (integer)

Classi

Le API di questo modulo aderiscono il più possibile allo standard DOM di livello 2. Di conseguenza le API sono completamente orientate agli oggetti. Si ritiene una buona idea avere disponibile lo standard DOM quando si utilizza questo modulo. Sebbene le API siano orientate agli oggetti, vi sono alcune funzioni che possono essere richiamate in modo non orientato agli oggetti, passando l'oggetto su cui operare come primo argomento. Queste funzioni sono state mantenute per compatibilità verso le vecchie versioni del modulo, ma non se ne incoraggia l'uso nello sviluppo di nuovi prodotti.

Queste API differiscono della API DOM ufficiali per due aspetti. Primo, gli attributi della classe sono implermentati come funzioni con il medesimo nome e, secondo, i nomi delle funzioni seguono la convenzione del PHP. Questo significa che la funzione DOM lastChild() sarà chiamata last_child().

In questo modulo sono definite diverse classi, queste saranno elencate - compresi i loro metodi - nella seguente tabella. Le classi con un equivalente nello standard DOM sono chiamate DOMxxx.

Tabella 3. Elenco delle classi

Nome della classe	Classe genitrice
DomAttribute	DomNode
DomCData	DomNode
DomComment	DomCData : DomNode
DomDocument	DomNode
DomDocumentType	DomNode
DomElement	DomNode
DomEntity	DomNode
DomEntityReference	DomNode
DomProcessingInstruction	DomNode
DomText	DomCData : DomNode
Parser	Attualmente chiamata DomParser
XPathContext

Tabella 4. Classe DomDocument (DomDocument : DomNode)

Metodi	Funzioni	Note
doctype	DomDocument_doctype()
document_element	DomDocument_document_element()
create_element	DomDocument_create_element()
create_text_node	DomDocument_create_text_node()
create_comment	DomDocument_create_comment()
create_cdata_section	DomDocument_create_cdata_section()
create_processing_instruction	DomDocument_create_processing_instruction()
create_attribute	DomDocument_create_attribute()
create_entity_reference	DomDocument_create_entity_reference()
get_elements_by_tagname	DomDocument_get_elements_by_tagname()
get_element_by_id	DomDocument_get_element_by_id()
dump_mem	DomDocument_dump_mem()	non standard DOM
dump_file	DomDocument_dump_file()	non standard DOM
html_dump_mem	DomDocument_html_dump_mem()	non standard DOM
xpath_init	xpath_init	non standard DOM
xpath_new_context	xpath_new_context	non standard DOM
xptr_new_context	xptr_new_context	non standard DOM

Tabella 5. Classe DomElement (DomElement : DomNode)

Metodo	Funzioni	Note
tagname	DomElement_tagname()
get_attribute	DomElement_get_attribute()
set_attribute	DomElement_set_attribute()
remove_attribute	DomElement_remove_attribute()
get_attribute_node	DomElement_get_attribute_node()
get_elements_by_tagname	DomElement_get_elements_by_tagname()
has_attribute	DomElement_has_attribute()

Tabella 6. Classe DomNode

Metodo	Note
DomNode_node_name()
DomNode_node_value()
DomNode_node_type()
DomNode_last_child()
DomNode_first_child()
DomNode_child_nodes()
DomNode_previous_sibling()
DomNode_next_sibling()
DomNode_parent_node()
DomNode_owner_document()
DomNode_insert_before()
DomNode_append_child()
DomNode_append_sibling()	non standard DOM. Questa funzione emula il comportamento di DomNode_append_child().
DomNode_remove_child()
DomNode_has_child_nodes()
DomNode_has_attributes()
DomNode_clone_node()
DomNode_attributes()
DomNode_unlink_node()	non standard DOM
DomNode_replace_node()	non standard DOM
DomNode_set_content()	non standard DOM, deprecata
DomNode_get_content()	non standard DOM, deprecata
DomNode_dump_node()	non standard DOM
DomNode_is_blank_node()	non standard DOM

Tabella 7. Classe DomAttribute (DomAttribute : DomNode)

Metodo		Note
name	DomAttribute_name()
value	DomAttribute_value()
specified	DomAttribute_specified()

Tabella 8. Classe DomProcessingInstruction (DomProcessingInstruction : DomNode)

Metodo	Funzione	Note
target	DomProcessingInstruction_target()
data	DomProcessingInstruction_data()

Tabella 9. Classe Parser class

Metodo	Funzione	Note
add_chunk	Parser_add_chunk()
end	Parser_end()

Tabella 10. Classe XPathContext

Metodo	Funzione	Note
eval	XPathContext_eval()
eval_expression	XPathContext_eval_expression()
register_ns	XPathContext_register_ns()

Tabella 11. Classe DomDocumentType (DomDocumentType : DomNode)

Metodo	Funzione	Note
name	DomDocumentType_name()
entities	DomDocumentType_entities()
notations	DomDocumentType_notations()
public_id	DomDocumentType_public_id()
system_id	DomDocumentType_system_id()
internal_subset	DomDocumentType_internal_subset()

La classe DomDtd è derivata da DomNode. Mentre DomComment è derivata da DomCData

Esempi

Diversi esempi presenti in questo manuale richiedono un testo XML. Anzichè ripetere questo testo in ogni esempio, si inserirà il testo in un file che verrà incluso in ogni esempio. Questo file di include verrà illustrato nel seguente esempio. Si può anche creare un documento XML e leggerlo con DomDocument_open_file().

Esempio 1. File di include example.inc con testo XML
<?php $xmlstr = "<?xml version='1.0' standalone='yes'?> <!DOCTYPE chapter SYSTEM '/share/sgml/Norman_Walsh/db3xml10/db3xml10.dtd' [ <!ENTITY sp \"spanish\"> ]>  <chapter language='en'><title language='en'>Title</title> <para language='ge'> sp;  <informaltable ID='findme' language='&sp;'> <tgroup cols='3'> <tbody> <row><entry>a1</entry><entry morerows='1'>b1</entry><entry>c1</entry></row> <row><entry>a2</entry><entry>c2</entry></row> <row><entry>a3</entry><entry>b3</entry><entry>c3</entry></row> </tbody> </tgroup> </informaltable> </para> </chapter>"; ?>

Sommario
DomAttribute->name -- Restituisce il nome di un attributo
DomAttribute->set_value -- Sets the value of an attribute
DomAttribute->specified -- Verifica se l'attributo è presente
DomAttribute->value -- Restituisce il valore di un attributo
DomDocument->add_root -- Aggiunge un nodo radice [deprecated]
DomDocument->create_attribute -- Crea un nuovo attributo
DomDocument->create_cdata_section -- Crea un nuovo nodo cdata
DomDocument->create_comment -- Crea un nodo commento
DomDocument->create_element_ns -- Crea un nodo elemento con il relativo spazio dei nomi
DomDocument->create_element -- Crea un nodo elemento
DomDocument->create_entity_reference --
DomDocument->create_processing_instruction -- Crea un nuovo nodo PI
DomDocument->create_text_node -- Crea un nodo di testo
DomDocument->doctype -- Restituisce il tipo di documento
DomDocument->document_element -- Restituisce il nodo radice
DomDocument->dump_file -- Scarica in un file l'albero XML interno
DomDocument->dump_mem -- Scarica in una stringa la struttura XML interna
DomDocument->get_element_by_id -- Ricerca di un elemento per id
DomDocument->get_elements_by_tagname -- Restituisce un elemento dato il tag
DomDocument->html_dump_mem -- Scarica la struttura XML interna in una stringa come HTML
DomDocument->xinclude -- Sostituisce gli XIncludes in un oggetto DomDocument
DomDocumentType->entities -- Restituisce l'elenco delle entità
DomDocumentType->internal_subset -- Restituisce un subset interno
DomDocumentType->name -- Restituisce il nome del tipo documento
DomDocumentType->notations -- Restituisce la lista delle notazioni
DomDocumentType->public_id -- Restituisce l'identificatore pubblico del tipo documento
DomDocumentType->system_id -- Restituisce l'identificativo di sistema del tipo documento
DomElement->get_attribute_node -- Restituisce il nodo dell'attributo dato
DomElement->get_attribute -- Restituisce il valore di un attributo
DomElement->get_elements_by_tagname -- Restituisce l'elemento con il tag dato
DomElement->has_attribute -- Verifica l'esistenza dell'attributo
DomElement->remove_attribute -- Rimuove un attributo
DomElement->set_attribute -- Valorizza un attributo
DomElement->tagname -- Restituisce il nome dell'elemento corrente
DomNode->add_namespace -- Aggiunge la dichiarazione dello spazio dei nomi ad un nodo
DomNode->append_child -- Accoda un nuovo figlio
DomNode->append_sibling -- Aggiunge un nodo fratello
DomNode->attributes -- Restituisce la lista degli attributi
DomNode->child_nodes -- Restituisce i figli di un nodo
DomNode->clone_node -- Clona un nodo
DomNode->dump_node -- Scarica un singolo nodo
DomNode->first_child -- Restituisce il primo nodo figlio
DomNode->get_content -- Restituisce il contenuto del nodo
DomNode->has_attributes -- Verifica se il nodo ha attributi
DomNode->has_child_nodes -- Verifica se esistono nodi figlio
DomNode->insert_before -- Inserisce un nuovo nodo come figlio
DomNode->is_blank_node -- Verifica se il nodo è vuoto
DomNode->last_child -- Restituisce l'ultimo nodo figlio del nodo
DomNode->next_sibling -- Restituisce il successivo fratello del nodo
DomNode->node_name -- Restituisce il nome del nodo
DomNode->node_type -- Restituisce il tipo di nodo
DomNode->node_value -- Restituisce il valore di un nodo
DomNode->owner_document -- Restituisce il documento a cui appartiene questo nodo
DomNode->parent_node -- Restituisce il genitore del nodo
DomNode->prefix -- Restituisce lo spazio dei nomi prefisso al nodo
DomNode->previous_sibling -- Restituisce il nodo fratello precedente
DomNode->remove_child -- Rimuove un nodo figlio dalla lista dei figli
DomNode->replace_child -- Sostituisce un nodo figlio
DomNode->replace_node -- Sostituisce il nodo
DomNode->set_content -- Imposta il contenuto del nodo
DomNode->set_name -- Imposta il nome del nodo
DomNode->set_namespace -- Imposta lo spazio dei nomi del nodo
DomNode->unlink_node -- Rimuove il nodo
DomProcessingInstruction->data -- Restituisce i dati di un nodo PI
DomProcessingInstruction->target -- Restituisce il target di un nodo PI
DomXsltStylesheet->process -- Applica una trasformazione XSLT ad un oggetto DomDocument
DomXsltStylesheet->result_dump_file -- Scarica il risultato di una trasformazione XSLT in un file
DomXsltStylesheet->result_dump_mem -- Scarica il risultato di una trasformazione XSLT in una stringa
domxml_new_doc -- Crea un nuovo documento XML vuoto
domxml_open_file -- Crea un oggetto DOM da un file XML
domxml_open_mem -- Crea un oggetto DOM da un documento XML
domxml_version -- restituisce la versione della libreria XML
domxml_xmltree -- Crea un albero di oggetti PHP da un documento XML
domxml_xslt_stylesheet_doc -- Crea un oggetto DomXsltStylesheet da un oggetto DomDocument.
domxml_xslt_stylesheet_file -- Crea un oggetto DomXsltStylesheet da un file con un documento XSL
domxml_xslt_stylesheet -- Crea un oggetto DomXsltStylesheet da un documento XML contenuto in una stringa
domxml_xslt_version -- Gets the XSLT library version
xpath_eval_expression -- Valuta il percorso XPath nella stringa data
xpath_eval -- Valuta il percorso XPath nella stringa data
xpath_new_context -- Crea un nuovo contesto xpath
xpath_register_ns_auto -- Register the given namespace in the passed XPath context
xpath_register_ns -- Register the given namespace in the passed XPath context
xptr_eval -- Valuta il percorso della locazione XPtr nella stringa data
xptr_new_context -- Crea un nuovo contesto XPath

DomAttribute->name

(no version information, might be only in CVS)

DomAttribute->name -- Restituisce il nome di un attributo

Descrizione

string DomAttribute->name ( void )

La funzione restituisce il nome di un attributo.

Vedere anche domattribute_value() per un esempio.

DomAttribute->set_value

(no version information, might be only in CVS)

DomAttribute->set_value -- Sets the value of an attribute

Descrizione

class DomAttribute {

bool set_value ( string content )

}

This function sets the value of an attribute.

Elenco dei parametri

content: The new value.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Migrating to PHP 5

Set the value property of DOMAttr.

Vedere anche:

DomAttribute->value

DomAttribute->specified

(no version information, might be only in CVS)

Questa funzione restituisce una nuova istanza della classe DomEntityReference. Il contenuto dell'entità è passato tramite il parametro. Questo nodo non sarà presente nel documento fino a quando non viene inserito con funzioni tipo domnode_append_child().

La funzione restituisce FALSE se si verifica un errore.

DomDocument->create_processing_instruction

(no version information, might be only in CVS)

DomDocument->create_processing_instruction -- Crea un nuovo nodo PI

Descrizione

domprocessinginstruction DomDocument->create_processing_instruction ( string contenuto )

Questa funzione restituisce una nuova istanza della classe DomCData. Il contenuto della PI viene passato tramite il parametro.Questo nodo non sarà presente nel documento fino a quando non viene inserito con funzioni tipo domnode_append_child().

La funzione restituisce FALSE se si verifica un errore.

Vedere anche domnode_append_child(), domdocument_create_element(), domdocument_create_text(), domdocument_create_cdata_section(), domdocument_create_attribute(), domdocument_create_entity_reference() e domnode_insert_before().

DomDocument->create_text_node

(no version information, might be only in CVS)

DomDocument->create_text_node -- Crea un nodo di testo

Descrizione

domtext DomDocument->create_text_node ( string contenuto )

string DomDocument->dump_file ( string nomefile [, bool compressione [, bool formato]] )

La funzione crea un documento XML dalla rappresentazione DOM. Solitamente questa funzione viene richiamata dopo avere creato da zero un nuovo documento XML, come nell'esempio seguente. Il parametro formato specifica se l'output debba essere ben formattato o meno. Il primo parametro specifica il nome del file ed il secondo se debba essere compresso o meno.

Esempio 1. Creazione dell'intestazione di un documento HTML
<?php $doc = domxml_new_doc("1.0"); $root = $doc->create_element("HTML"); $root = $doc->append_child($root); $head = $doc->create_element("HEAD"); $head = $root->append_child($head); $title = $doc->create_element("TITLE"); $title = $head->append_child($title); $text = $doc->create_text_node("This is the title"); $text = $title->append_child($text); $doc->dump_file("/tmp/test.xml", false, true); ?>

Vedere anche domdocument_dump_mem() e domdocument_html_dump_mem().

DomDocument->dump_mem

(no version information, might be only in CVS)

DomDocument->dump_mem -- Scarica in una stringa la struttura XML interna

Descrizione

string DomDocument->dump_mem ( [bool formato [, string codifica]] )

Avvertimento

La funzione crea un docuemnto XML dalla rappresentazione DOM. Solitamente si richiama questa funzione dopo avere creato un nuovo documento DOM da zero, come nell'esempio seguente. Il parametro formato specifica se l'output debba essere ben formattato o meno.

Nota: Il primo parametro è stato inserito nella versione 4.3.0 di PHP.

Vedere anche domdocument_dump_file() e domdocument_html_dump_mem().

DomDocument->get_element_by_id

(no version information, might be only in CVS)

DomDocument->get_element_by_id -- Ricerca di un elemento per id

Descrizione

domelement DomDocument->get_element_by_id ( string id )

Questa funzione è simile a domdocument_get_elements_by_tagname() ma ricerca un elemento per un dato id. In accordo con lo standard DOM, è richiesto un DTD che definisca l'attributo ID essere di tipo ID, sebbene l'implementazione corrente ricerchi semplicemente il testo "//*[@ID = '%s']". Ciò non è aderente allo standard DOM che richiede di restituire null se non è noto quale sia l'attributo di tipo id. Questo comportamento sta per essere corretto, pertanto non basarsi sull'implementazione odierna.

Vedere anche domdocument_get_elements_by_tagname()

DomDocument->get_elements_by_tagname

(no version information, might be only in CVS)

domattribute DomElement->get_attribute_node ( string name )

Restituisce il nodo dell'attributo indicato da name nell'elemento corrente. Il parametro name distingue tra minuscole e maiuscole.

Se non si trova alcun attributo con il nome dato, la funzione restituisce FALSE

Esempio 1. Ottenere un nodo attributo
<?php include("example.inc"); if (!$dom = domxml_open_mem($xmlstr)) { echo "Error while parsing the document\n"; exit; } $root = $dom->document_element(); if ($attribute = $root->get_attribute_node('language')) { echo 'Language is: ' . $attribute->value() . "\n"; } ?>

DomElement->get_attribute

(no version information, might be only in CVS)

DomElement->get_attribute -- Restituisce il valore di un attributo

Descrizione

object DomElement->get_attribute ( string nome )

domattribute DomElement->set_attribute ( string nome, string valore )

Imposta l'attributo chiamato nome al valore fornito. Se l'attributo non esiste lo crea.

Esempio 1. Valorizzazione di un attributo
<?php $doc = domxml_new_doc("1.0"); $node = $doc->create_element("para"); $newnode = $doc->append_child($node); $newnode->set_attribute("align", "left"); ?>

Vedere anche domelement_get_attribute()

DomElement->tagname

(no version information, might be only in CVS)

DomElement->tagname -- Restituisce il nome dell'elemento corrente

Descrizione

string DomElement->tagname ( void )

Returns the name of the current node. Chiamare questa funzione è come accedere alla proprietà tagname del nodo corrente, o chiamare DomElement->node_name().

Esempio 1. Ottenere il nome del nodo
<?php include("example.inc"); if (!$dom = domxml_open_mem($xmlstr)) { echo "Error while parsing the document\n"; exit; } $root = $dom->document_element(); echo $root->tagname(); // chapter echo $root->tagname; // chapter echo $root->node_name(); // chapter ?>

DomNode->add_namespace

(no version information, might be only in CVS)

DomNode->add_namespace -- Aggiunge la dichiarazione dello spazio dei nomi ad un nodo

Descrizione

bool DomNode->add_namespace ( string uri, string prefix )

Vedere anche domdocument_create_element_ns() e domnode_set_namespace()

DomNode->append_child

(no version information, might be only in CVS)

DomNode->append_child -- Accoda un nuovo figlio

Descrizione

domelement DomNode->append_child ( domelement newnode )

Questa funzione accoda un nodo figlio ad un elenco pre-esistente di figli oppure crea una nuova lista di figli. Il nodo figlio può essere creato con funzioni tipo domdocument_create_element(), domdocument_create_text() ecc. oppure usando un qualsiasi altro nodo.

(PHP < 4.3) Prima che sia aggiunto un nuovo nodo questo viene duplicato. Quindi il nuovo nodo è una nuova copia che può essere modificata senza variare il nodo passato alla funzione. Se il nodo ha dei nodi figli, anche questi saranno duplicati, ciò rende facile duplicare grandi parti di un documento XML. Il valore restituito è il nodo figlio accodato. Se si prevede di fare ulteriori modifiche al nodo aggiunto, occorre usare il nodo restituito.

(PHP 4.3.0/4.3.1) Il nuovo nodo figlio nuovo_nodo viene prima rimosso dal contesto esistente, se ne è già un figlio di DomNode. Quindi viene mosso e non più copiato.

(PHP >= 4.3.2) Il nuovo nodo figlio nuovo_nodo viene prima rimosso dal contesto esistente, se ne esiste uno nel documento. Quindi viene mosso e non più copiato. Questo comportamento si attiene alle specifiche W3C. Se si desidera duplicare una grande parte di un documento XML, occorre utilizzare DomNode->clone_node() prima di accodare il nodo.

Nel seguente esempio si accoderà un nuovo nodo ad un documento e si imposterà l'attributo "align" a "left".
Esempio 1. Aggiunta di un nodo figlio
<?php $doc = domxml_new_doc("1.0"); $node = $doc->create_element("para"); $newnode = $doc->append_child($node); $newnode->set_attribute("align", "left"); ?>
L'esempio precedente può anche essere scritto:
Esempio 2. Aggiunta di un nodo figlio
<?php $doc = domxml_new_doc("1.0"); $node = $doc->create_element("para"); $node->set_attribute("align", "left"); $newnode = $doc->append_child($node); ?>
Il seguente è un esempio più complesso. Prima cerca un dato elemento, quindi lo si duplica, compresi i suoi figli, lo si aggiunge come un fratello. Infine si aggiunge un attributo ad uno dei figli del nuovo nodo e quindi si scarica il documento.
Esempio 3. Aggiunta di un nodo figlio
<?php include("example.inc"); if (!$dom = domxml_open_mem($xmlstr)) { echo "Error while parsing the document\n"; exit; } $elements = $dom->get_elements_by_tagname("informaltable"); print_r($elements); $element = $elements[0]; $parent = $element->parent_node(); $newnode = $parent->append_child($element); $children = $newnode->children(); $attr = $children[1]->set_attribute("align", "left"); echo "<pre>"; $xmlfile = $dom->dump_mem(); echo htmlentities($xmlfile); echo "</pre>"; ?>
L'esempio precedente può anche essere svolto con domnode_insert_before() invece di domnode_append_child().

Vedere anche domnode_insert_before() e domnode_clone_node().

DomNode->append_sibling

(no version information, might be only in CVS)

DomNode->append_sibling -- Aggiunge un nodo fratello

Descrizione

object DomNode->append_sibling ( object nuovo_nodo )

Questa funzione aggiunge un nodo di pari livello rispetto ad un nodo esistente. Il nodo figlio può essere creato con funzioni del tipo domdocument_create_element(), domdocument_create_text() ecc. oppure utilizzando un'altro nodo.

string DomNode->dump_node ( void )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Vedere anche domdocument_dump_mem().

DomNode->first_child

(no version information, might be only in CVS)

DomNode->first_child -- Restituisce il primo nodo figlio

Descrizione

object DomNode->first_child ( void )

Restituisce il primo nodo figlio.

(PHP >= 4.3 solo) Se non si trova il primo figlio, si restituisce NULL.

Vedere anche domnode_last_child(), domnode_next_sibling() e domnode_previous_sibling().

DomNode->get_content

(no version information, might be only in CVS)

DomNode->get_content -- Restituisce il contenuto del nodo

Descrizione

string DomNode->get_content ( void )

Questa funzione restituisce il contenuto del nodo

Esempio 1. Ottenere il contenuto di un nodo
<?php if (!$dom = domxml_open_mem($xmlstr)) { echo "Error while parsing the document\n"; exit; } $root = $dom->document_element(); $node_array = $root->get_elements_by_tagname("element"); for ($i = 0; $i<count($node_array); $i++) { $node = $node_array[$i]; echo ("The element[$i] is: ".$node->get_content()); } ?>

DomNode->has_attributes

(no version information, might be only in CVS)

DomNode->has_attributes -- Verifica se il nodo ha attributi

Descrizione

bool DomNode->has_attributes ( void )

Questa funzione verifica se il nodo ha attributi.

Vedere anche domnode_has_child_nodes().

DomNode->has_child_nodes

(no version information, might be only in CVS)

DomNode->has_child_nodes -- Verifica se esistono nodi figlio

Descrizione

bool DomNode->has_child_nodes ( void )

Questa funzione verifica se il nodo ha nodi figlio.

Vedere anche domnode_child_nodes().

DomNode->insert_before

(no version information, might be only in CVS)

DomNode->insert_before -- Inserisce un nuovo nodo come figlio

Descrizione

object DomNode->insert_before ( object nuovo_nodo, object nodo_riferimento )

Questa funzione inserisce il nuovo_nodo a destra rispetto al nodo_riferimento. La funzione restituisce il nodo inserito. Occorre utilizzare questo valore se si intende apportare nuove modifiche al nodo appena accodato.

(PHP >= 4.3 solo) Se nuovo_nodo è già parte del documento, prima questo verrà scollegato dal contesto esistente. Se nodo_riferimento vale NULL, allora nuovo_nodo sarà inserito alla fine della lista dei nodi figlio.

La funzione domnode_insert_before() è molto simile a domnode_append_child() come illustrato nel seguente esempio nel quale si ha lo stesso comportamento visto nell'esempio di domnode_append_child().

Esempio 1. Aggiunta di un nodo figlio
<?php include("example.inc"); if (!$dom = domxml_open_mem($xmlstr)) { echo "Error while parsing the document\n"; exit; } $elements = $dom->get_elements_by_tagname("informaltable"); print_r($elements); $element = $elements[0]; $newnode = $element->insert_before($element, $element); $children = $newnode->children(); $attr = $children[1]->set_attribute("align", "left"); echo "<pre>"; $xmlfile = $dom->dump_mem(); echo htmlentities($xmlfile); echo "</pre>"; ?>

Vedere anche domnode_append_child().

DomNode->is_blank_node

(no version information, might be only in CVS)

DomNode->is_blank_node -- Verifica se il nodo è vuoto

string DomNode->node_name ( void )

Restituisce il nome del nodo. Il nome ha diversi significati per i differenti tipi di nodi, come sarà illustrato nella tabella seguente.

Tabella 1. Significato dei valori

Tipo	Significato
DomAttribute	valori di attributo
DomAttribute
DomCDataSection	#cdata-section
DomComment	#comment
DomDocument	#document
DomDocumentType	nome del tipo documento
DomElement	nome tag
DomEntity	nome di entittà
DomEntityReference	nome di entità di riferimento
DomNotation	nome della notazione
DomProcessingInstruction	target
DomText	#text

DomNode->node_type

(no version information, might be only in CVS)

DomNode->node_type -- Restituisce il tipo di nodo

Descrizione

int DomNode->node_type ( void )

La funzione restituisce il tipo di nodo. L'elenco di tutti i tipi possibili sono elencati in una tabella nell'introduzione.

Esempio 1.

<?php
 
include 'example.inc';
 
$dom = domxml_open_mem($xmlstr);
 
$chapter = $dom->document_element();
 
// Let's see the elements contained in chapter
foreach($chapter->child_nodes() as $node) {
  if ($node->node_type() == XML_ELEMENT_NODE) {
    echo $node->node_name() . "\n";
  }
}
 
?>

Il precedente esempio visualizzerà:

title
para

DomNode->node_value

(no version information, might be only in CVS)

DomNode->node_value -- Restituisce il valore di un nodo

Descrizione

string DomNode->node_value ( void )

La funzione restituisce il valore di un nodo. Il valore ha diversi significati per i diversi tipi di nodi, come illustrato nella seguente tabella.

Tabella 1. Significato dei valori

Tipo	Significato
DomAttribute	valori di un attributo
DomAttribute
DomCDataSection	contenuto
DomComment	contenuto del commento
DomDocument	null
DomDocumentType	null
DomElement	null
DomEntity	null
DomEntityReference	null
DomNotation	null
DomProcessingInstruction	l'intero contenuto senza destinatario
DomText	contenuto del testo

DomNode->previous_sibling -- Restituisce il nodo fratello precedente

object DomXsltStylesheet->process ( object DomDocument [, array xslt_parameters [, bool param_is_xpath]] )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Vedere anche domxml_xslt_stylesheet(), domxml_xslt_stylesheet_file() e domxml_xslt_stylesheet_doc().

DomXsltStylesheet->result_dump_file

(no version information, might be only in CVS)

DomXsltStylesheet->result_dump_file -- Scarica il risultato di una trasformazione XSLT in un file

Descrizione

string DomXsltStylesheet->result_dump_file ( object DomDocument, string filename )

Avvertimento

Questa funzione è disponibile solo a partire dalla versione 4.3 di PHP.

Poichè DomXsltStylesheet->process() restituisce sempre un documento XML ben formato, a prescindere da quale metodo di output sia specificato in <xsl:output> od in attributi/elementi simili, questa non è di grande utilità se si desidera ottenere in output un testo normale o HTML. Al contrario questa funzione rispetta <xsl:output method="html|text"> e le altre direttive di output. Vedere l'esempio per dettagli su come usare la funzione.

Esempio 1. Salvataggio del risultato di una trasformazione XSLT in un file.
<?php $filename = "stylesheet.xsl"; $xmldoc = domxml_open_file("data.xml"); $xsldoc = domxml_xslt_stylesheet_file($filename); $result = $xsldoc->process($xmldoc); echo $xsldoc->result_dump_file($result, "filename"); ?>

Vedere anche domxml_xslt_result_dump_mem() e domxml_xslt_process()

DomXsltStylesheet->result_dump_mem

(no version information, might be only in CVS)

DomXsltStylesheet->result_dump_mem -- Scarica il risultato di una trasformazione XSLT in una stringa

Descrizione

string DomXsltStylesheet->result_dump_mem ( object DomDocument )

Avvertimento

Questa funzione è disponibile solo a partire dalla versione 4.3 di PHP.

Esempio 1. Visualizzazione del risultato di una trasformazione XSLT.
<?php $filename = "stylesheet.xsl"; $xmldoc = domxml_open_file("data.xml"); $xsldoc = domxml_xslt_stylesheet_file($filename); $result = $xsldoc->process($xmldoc); echo $xsldoc->result_dump_mem($result); ?>

Vedere anche domxml_xslt_result_dump_file() e domxml_xslt_process()

domxml_new_doc

(PHP 4 >= 4.2.1, PECL)

string domxml_version ( void )

Questa funzione restituisce la versione della libreria XML attualmente utilizzata.

domxml_xmltree

(PHP 4 >= 4.2.1, PECL)

domxml_xmltree -- Crea un albero di oggetti PHP da un documento XML

int domxml_xslt_version ( void )

Gets the XSLT library version.

Valori restituiti

Returns the version number of the XSLT library, as an integer.

Esempi

Esempio 1. domxml_xslt_version() Example
<?php echo domxml_xslt_version(); ?>
Il precedente esempio visualizzerà qualcosa simile a:
10112

Vedere anche:

domxml_version()

xpath_eval_expression

(PHP 4 >= 4.0.4, PECL)

xpath_eval_expression -- Valuta il percorso XPath nella stringa data

Descrizione

array xpath_eval_expression ( object xpath_context )

Avvertimento

Vedere anche xpath_eval().

xpath_eval

(PHP 4 >= 4.0.4, PECL)

xpath_eval -- Valuta il percorso XPath nella stringa data

Descrizione

array xpath_eval ( object xpath context, string xpath expression [, object contextnode] )

Avvertimento

Si può specificare il parametro opzionale contextnode per eseguire delle query XPath relative.

Vedere anche xpath_new_context().

xpath_new_context

(PHP 4 >= 4.0.4, PECL)

xpath_new_context -- Crea un nuovo contesto xpath

Descrizione

object xpath_new_context ( object dom document )

Avvertimento

Vedere anche xpath_eval().

xpath_register_ns_auto

(PECL)

xpath_register_ns_auto -- Register the given namespace in the passed XPath context

Descrizione

bool xpath_register_ns_auto ( XPathContext xpath_context [, object context_node] )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

xpath_register_ns()

xpath_register_ns

(PHP 4 >= 4.2.0, PECL)

xpath_register_ns -- Register the given namespace in the passed XPath context

Descrizione

bool xpath_register_ns ( XPathContext xpath_context, string prefix, string uri )

Introduzione

Le seguenti sono le funzioni per la gestione degli errori ed il logging. Esse permettono di definire regole personalizzate per la gestione degli errori, e anche di modificarne la modalità della gestione stessa. Ciò permette di cambiare ed integrare i messaggi di errore adattandoli alle vostre esigenze.

Grazie alle funzioni di logging, è possibile inviare messaggi direttamente ad altre macchine, alla posta elettronica (o ad un gateway pager o di posta elettronica!), ai log di sistema, ecc., in modo da effettuare il log e controllare selettivamente le parti più importanti delle vostre applicazioni e siti web.

Le funzioni di restituzione dell'errore consentono la personalizzazione del livello e del tipo di errore, dal semplice avviso sino a funzioni personalizzate restituite durante gli errori.

Requisiti

Non sono necessarie librerie esterne per utilizzare questo modulo.

Installazione

Non è necessaria nessuna installazione per usare queste funzioni, esse fanno parte del core di PHP.

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

Tabella 1. Parametri di configurazione per la gestione degli errori e dei log

Nome	Default	Modificabile
error_reporting	E_ALL & ~E_NOTICE	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
ignore_repeated_errors	"0"	PHP_INI_ALL
ignore_repeated_source	"0"	PHP_INI_ALL
report_memleaks	"1"	PHP_INI_ALL
track_errors	"0"	PHP_INI_ALL
html_errors	"1"	PHP_INI_ALL
docref_root	""	PHP_INI_ALL
docref_ext	""	PHP_INI_ALL
error_prepend_string	NULL	PHP_INI_ALL
error_append_string	NULL	PHP_INI_ALL
error_log	NULL	PHP_INI_ALL
warn_plus_overloading	NULL	PHP_INI??

Per maggiori dettaglii e per le definizioni delle costanti PHP_INI_* vedere ini_set().

Breve descrizione dei parametri di configurazione.

error_reporting integer

Imposta il livello di errore da visualizzare. Il parametro è sia un intero rappresentante un campo di bit, o una costante nominale. I livelli ri report degli errori e le costanti previste sono descritte in Costanti Predefinite, e in php.ini. Per impostare il livello in fase di esecuzione utilizzare la funzione error_reporting(). Vedere anche il parametro display_errors.

In PHP 4 e PHP 5 il valore di default è E_ALL & ~E_NOTICE. Questa impostazione non visualizza gli errori di livello E_NOTICE. Tuttavia può essere comodo visualizzare questi messaggi in fase di sviluppo.

Nota: Abilitare E_NOTICE durante la fase di sviluppo ha dei benefici. Ad esempio per scopi di debug: i messaggi di tipo NOTICE avvisano su possibili bug nel codice. L'uso di variabili non assegnate, ad esempio, viene rilevato con questo livello di errore. Particolare che è molto utile per trovare errori di battitura e risparmiare tempo in fase di debug. I messaggi di tipo NOTICE segnalano il codice scritto con un cattivo stile. Ad esempio, $arr[item] è meglio che sia scritto come $arr['item'] poichè il PHP tenta di trattare "item" come costante. Se non esiste una simile costante, il PHP presume che si tratti dell'indice di una matrice.

Nota: Nel PHP 5 è stato introdotto un nuovo livello di errore E_STRICT. Come E_STRICT non viene incluso nel E_ALL e, pertanto, occorre abilitarlo in modo esplicito. Abilitare E_STRICT durante la fase di sviluppo porta alcuni benefici. Questa casistica di messaggi servono ad aiutare le più recenti, e consigliate, metodologie di programamzione, avvisando, ad esempio, sull'uso di funzioni deprecate.

In PHP 3 l'impostazione di default è (E_ERROR | E_WARNING | E_PARSE), che significa la medesima cosa. Occorre rilevare, tuttavia, che le costanti non sono supportate nel php3.ini del PHP 3, e pertanto occorre utilizzare la codifica numerica, che corrisponde a 7.

display_errors boolean

Questo parametro determina se gli errori devono essere visualizzati sullo schermo come parte dell'output o se devono essere nascosti all'utente.

Nota: Questa opzione è di supporto allo sviluppo, e non deve mai essere utilizzata nei sistemi di produzione (ad esempio collegati ad Internet).

display_startup_errors boolean

Anche quando è abilitata la visualizzazione degli errori, gli errori che avvengono durante l'avvio del PHP non sono visualizzati. Si raccomanda di mantenere display_startup_errors impostato a off, tranne che nelle fasi di sviluppo.

log_errors boolean

Indica se i messaggi di errore debbano essere registrati nell'errorlog del server o in error_log. Questo opzione dipende dal server.

Nota: Sui siti di produzione si raccomanda di utilizzare la registrazione degli errori piuttosto che visualizzarli.

log_errors_max_len integer

Imposta la massima lunghezza del log degli errori in byte. Nell'errorlog error_log viene indicata anche la fonte del messaggio. Il valore di default è 1024 e 0 indica di non applicare alcuna limitazione. Questa dimensione viene applicata agli errori registrati, agli errori visualizzati e anche a $php_errormsg.

When an integer is used, the value is measured in bytes. You may also use shorthand notation as described in this FAQ.

ignore_repeated_errors boolean

Non registra i messaggi ripetuti. Gli errori ripetutti sono gli errori che si verificano nel medesimo file nella linea, e vengono riportati sino a quando ignore_repeated_source non viene impostato a true.

ignore_repeated_source boolean

Ignora la fonte del messaggio quando si ignora i messaggi ripetuti. Quando questa impostazione è a On non saranno registrati messaggi ripetutida differenti linee del codice.

report_memleaks boolean

Se questo parametro è impostato a Off, non saranno evidenziate carenze di memoria (o nello stdout o nel log). Questa impostazione ha effetto solo nella compila in modalità di debug, e se error_reporting include E_WARNING nell'elenco degli errori abilitati.

track_errors boolean

Se abilitato, l'ultimo messaggio di errore sarà sempre presente nella variabile $php_errormsg.

html_errors boolean

Disabilita i tag HTML nei messaggi di errore. Il nuovo formato per i messaggi in HTML produce un testo cliccabile che dirige l'utente alla pagina che descrive l'errore o la funzione che generato l'errore. Questi riferimenti sono influenzati da docref_root e docref_ext.

docref_root string

Nel nuovo formato degli errori è previsto un riferimento alla pagina che descrive l'errore o alla funzione che ha generato l'errore. Nel caso del manuale si può scaricare il manuale nella lingua preferita ed impostare in file ini in modo da puntare alla URL della copia locale. Se la copia locale è raggiungibile tramite '/manual/' si può utilizzare docref_root=/manual/. In aggiunta si può impostare docref_ext a riconoscere l'estensione dei file nella copia, es. docref_ext=.html. E' possibile utilizzare riferimenti esterni. Ad esempio, si può utilizzare docref_root=http://manual/en/ oppure docref_root="http://landonize.it/?how=url&theme=classic&filter=Landon &url=http%3A%2F%2Fwww.php.net%2F"

Il più delle volte si imposta docref_root ad un valore che termina con value to end with a slash '/'. But see the second example above which does not have nor need it.

Nota: Questa caratteristica è utile nello sviluppo poichè rende facile la ricerca della descrzione delle funzioni. Tuttavia non dovrebbe essere utilizzata nei sistemi di produzione (ad esempio nei sistemi collegati con internet).

docref_ext string

Vedere docref_root.

Nota: Il valore di docref_ext deve cominciare con un punto '.'.

error_prepend_string string

Testo da visualizzare prima del messaggio di errore.

error_append_string string

Testo da visualizzare dopo il messaggio di errore.

error_log string

Nome del file in cui gli errori devono essere registrati. Se si indica il nome speciale syslog, gli errori saranno inviati al log di sistema. Sui sistemi Unix, ciò significa syslog(3) e sui sistemi Windows NT indica l'event log. Il log di sistema non è supportato in Windows 95. Vedere anche: syslog().

warn_plus_overloading boolean

Se abilitata, questa opzione indica al PHP di visualizzare un warning quando si utilizza il segno (+) nelle stringhe. Questo rende più facile trovare gli script che richiedono di essere modificati nelle operazioni di concatenazione delle stringhe utilizzando (.).

Costanti predefinite

Le costanti qui elencate sono sempre disponibili in quanto parte del core di PHP.

Nota: Si possono utilizzare queste constanti in php.ini ma non all'esterno del PHP, tipo in in httpd.conf, dove occorre utilizzare in valori.

Tabella 2. Errori e log

Valore	Costante	Descrizione	Note
1	`E_ERROR` (integer)	Errori fatali di esecuzione. Questi indicano errori che non si possono ignorare, come, ad esempio, errori di allocazione della memoria. L'esecuzione dello script è bloccata.
2	`E_WARNING` (integer)	Warning di esecuzione (errori non fatali). L'esecuzione dello script non viene bloccata.
4	`E_PARSE` (integer)	Errore di parsing in fase di compila. Essendo errori di parsing sono generati dal parser del codice PHP.
8	`E_NOTICE` (integer)	Informazioni di esecuzione. Questo messaggio indica che lo script ha incontrato qualcosa che potrebbe indicare un errore, ma è una sitauzione che può accadere durante una normale esecuzione di uno script.
16	`E_CORE_ERROR` (integer)	Errori fatali che accadono durante la fase di inizializzazione del PHP. Questo è come un `E_ERROR`, tranne che viene generato dall'interno del PHP.	dal PHP 4
32	`E_CORE_WARNING` (integer)	Warning (errore non fatale) che accade durante la fase di inizializzazione del PHP. Questo è come un `E_WARNING`, tranne che viene generato dall'interno del PHP.	dal PHP 4
64	`E_COMPILE_ERROR` (integer)	Errore fatale di compila. Questo è come `E_ERROR`, tranne che viene generato dal motore Zend.	dal PHP 4
128	`E_COMPILE_WARNING` (integer)	Warning di compila (errore non fatale). Questo è come `E_WARNING`, tranne che viene generato dal motore Zend.	dal PHP 4
256	`E_USER_ERROR` (integer)	Messaggio di errore generato dall'utente. Questo è come `E_ERROR`, tranne che viene generato dal codice PHP tramite la funzione trigger_error().	dal PHP 4
512	`E_USER_WARNING` (integer)	Messaggio di warning generato dall'utente. Questo è come `E_WARNING`,tranne che viene generato dal codice PHP tramite la funzione trigger_error().	dal PHP 4
1024	`E_USER_NOTICE` (integer)	Messaggio di informazione generato dall'utente. Questo è come `E_NOTICE`, tranne che viene generato dal codice PHP tramite la funzione trigger_error().	dal PHP 4
2047	`E_ALL` (integer)	Tutti gli errori ed i warning supportati tranne quelli di livello `E_STRICT`.
2048	`E_STRICT` (integer)	Informazione di esecuzione. Abilitare questo messaggio per avere dal PHP suggerimenti sulle modifiche da apportare al codice per avere la migliore interoperabilità e compatibilità del codice.	dal PHP 5

I valori precedenti (sia numerici, sia simbolici) possono essere utilizzati per costruire delle maschere di bit che indichino quali errori visualizzare. Si può utilizzare gli operatori sui bit per combinare questi valori o per mascherare certi tipi di errori. Fare attenzione che soltanto '|', '~', '!', '^' e '&' sono compresi dal php.ini, e che nessun operatore sui bit è gestito dal php3.ini.

Esempi

Di seguito sarà illustrato un esempio di utilizzo delle procedure di gestione dell'errore in PHP. Qui si definisce una funzione di gestione dell'errore che registra le informazioni in un file (in formato XML) e invia tramite e-mail allo sviluppare dei messaggi in caso di errori critici.
Esempio 1. Esempio dell'utilizzo di della gestione degli erorri in uno script
<?php // attiveremo la nostra gestione degli errori error_reporting(0); // funzione personalizzata di gestione dell'errore function userErrorHandler($errno, $errmsg, $filename, $linenum, $vars) { // orario per la registrazione $dt = date("Y-m-d H:i:s (T)"); // definisce una matrice associativa con i messaggi di errore // in realtà i soli campi che saranno considerati sono // 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" ); // indica gli errori per i quali fare salvare la trace delle variabili $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; // salva nell'errorlog e invia un e-mail se vi sono errori critici 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"); // variabile non definita, genera un warning $t = I_AM_NOT_DEFINED; // definisce dei vettori $a = array(2, 3, "foo"); $b = array(5.5, 4.3, -1.6); $c = array(1, -3); // genera un errore utente $t1 = distance($c, $b) . "\n"; // un'altro errore utente $t2 = distance($b, "i am not an array") . "\n"; // genera un warning $t3 = distance($a, $b) . "\n"; ?>

Vedere anche:

Vedere anche syslog().

Sommario
debug_backtrace -- Genera una backtrace
debug_print_backtrace -- Stampa una backtrace
error_log -- invia un messaggio di errore
error_reporting -- definisce quali errori di PHP vengono restituiti
restore_error_handler -- Ripristina la precedente funzione di gestione dell'errore
restore_exception_handler -- Ripristina la funzione di gestione delle eccezioni definita in precedenza
set_error_handler -- Configura una funzione di gestione dell'errore definita dall'utente.
set_exception_handler -- Imposta una funzione di gestione delle eccezioni definita dall'utente
trigger_error -- Genera un messaggio a livello utente di errore/avviso/avvertimento message
user_error -- Genera un messaggio di errore/avviso/avvertimento a livello utente

debug_backtrace

(PHP 4 >= 4.3.0, PHP 5)

debug_backtrace -- Genera una backtrace

Descrizione

array debug_backtrace ( void )

debug_backtrace() genera una backtrace PHP e restituisce questa informazione sotto forma di array associativo. Gli elementi che possono venire restituiti sono elencati nella seguente tabella:

Tabella 1. Elementi restituibili dalla funzione debug_backtrace()

Nome	Tipo	Descrizione
funzione	string	Il nome della funzione corrente. Vedere anche __FUNCTION__.
riga	integer	Il numero della linea corrente. Vedere anche __LINE__.
file	string	Il nome del file corrente. Vedere anche __FILE__.
classe	string	Il nome della class corrente. Vedere anche __CLASS__
tipo	string	Il tipo di chiamata corrente. Se chiamata di metodo, viene restituito "->" is returned. Se chiamata di metodo statico, viene restituito "::". Se chiamata di funzione, non viene restituito niente.
args	array	Se all'interno di una funzione, elenca gli argomenti della funzione. Se all'interno di un file incluso, elenca i nomi del file incluso.

Di seguito un semplice esempio.

Esempio 1. debug_backtrace() example
<?php // filename: a.php function a_test($str) { echo "\nHi: $str"; var_dump(debug_backtrace()); } a_test('friend'); ?> <?php // filename: b.php include_once '/tmp/a.php'; ?>
Risultati durante l'esecuzione di /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" } }

Vedere anche trigger_error() and debug_print_backtrace().

debug_print_backtrace

(PHP 5)

debug_print_backtrace -- Stampa una backtrace

Descrizione

void debug_print_backtrace ( void )

debug_print_backtrace() stampa una backtrace PHP. Stampa le chiamate di funzione, i file included/required e tutto cio' che viene valutato dalla funzione eval().

Elenco dei parametri

Questa funzione non ha parametri.

Valori restituiti

No value is returned.

Esempi

Esempio 1. Esempio di funzione debug_print_backtrace()
<?php // include.php file function a() { b(); } function b() { c(); } function c(){ debug_print_backtrace(); } a(); ?> <?php // test.php file // questo e' il file che dovrebbe essere eseguito include 'include.php'; ?>
Il precedente esempio visualizzerà qualcosa simile a:
#0 eval() called at [/tmp/include.php:5] #1 a() called at [/tmp/include.php:17] #2 include(/tmp/include.php) called at [/tmp/test.php:3] #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]

Vedere anche:

debug_backtrace()

error_log

(PHP 3, PHP 4, PHP 5)

error_log -- invia un messaggio di errore

Descrizione

int error_log ( string messaggio [, int tipo_messaggio [, string destinazione [, string header_extra]]] )

Invia un messaggio di errore la log del server web, ad una porta TCP o ad un file. Il primo parametro, messaggio, è il messaggio di errore che deve essere registrato. Il secondo parametro, tipo_messaggio indica la destinazione del messaggio:

Tabella 1. error_log() tipi di log

0	`messaggio` è inviato al log di sistema di PHP, utilizzando il sistema di log del Sistema Operativo o un file, a seconda di come sia impostata la direttiva di configurazione error_log.
1	`messaggio` è inviato via posta elettronica all'indirizzo indicato nel parametro `destinazione` parameter. Questo è l'unico tipo di messaggio nel quale viene usato il quarto parametro, `headers_extra`. Questo tipo di messaggio utilizza la stessa funzione interna di mail().
2	`messaggio` viene inviato attraverso la connessione di debug di PHP. Questa opzione è disponibile solo nel caso che il debug remoto sia stato abilitato. In questo caso, il parametro `destinazione` specifica il nome dell'host o l'indirizzo IP e opzionalmente, numero di porta, del socket che riceverà l'informazione di debug.
3	`messaggio` è aggiunto al file `destinazione`.

Avvertimento

Il debug remoto via TCP/IP è una caratteristica di PHP 3 non disponibile in PHP 4.

Esempio 1. error_log() esempi
// Invia notifica via log del server se non è possibile // connettersi al database. if (!Ora_Logon ($username, $password)) { error_log ("Database Oracle non disponibile!", 0); } // Notifica via posta elettronica all'amministratore se esauriscono i FOO if (!($foo = allocate_new_foo()) { error_log ("Problemi seri, FOO esauriti!", 1, "operator@mydomain.com"); } // altri modi per chiamare error_log(): error_log ("Problema!", 2, "127.0.0.1:7000"); error_log ("Problema!", 2, "loghost"); error_log ("Problema!", 3, "/var/tmp/my-errors.log");

error_reporting

(PHP 3, PHP 4, PHP 5)

error_reporting -- definisce quali errori di PHP vengono restituiti

Description

int error_reporting ( [int livello] )

Definisce il livello di restituzione di errore di PHP e ritorna il vecchio livello. Il livello di restituzione dell'errore può essere una maschera di bit o una costante named. L'utilizzo delle costanti named è caldamente consigliato per assicurare la compatibilità con versioni future. All'aggiungere di livelli di errore, la gamma degli interi viene incrementata, perciò vecchi livelli di errore basati sull'intero non si comporteranno sempre come ci si aspetta.
Esempio 1. Error Integer changes
error_reporting (55); // Equivalente a E_ALL ^ E_NOTICE in PHP 3 /* ...in PHP 4, '55' indica (E_ERROR | E_WARNING | E_PARSE | E_CORE_ERROR | E_CORE_WARNING) */ error_reporting (2039); // Equivalente a E_ALL ^ E_NOTICE in PHP 4 error_reporting (E_ALL ^ E_NOTICE); // Il medesimo in PHP 3 e 4
Seguite i collegamenti delle costanti per conoscerne il significato:

Tabella 1. error_reporting() valori dei bit

valore	costante
1	E_ERROR
2	E_WARNING
4	E_PARSE
8	E_NOTICE
16	E_CORE_ERROR
32	E_CORE_WARNING
64	E_COMPILE_ERROR
128	E_COMPILE_WARNING
256	E_USER_ERROR
512	E_USER_WARNING
1024	E_USER_NOTICE
2047	E_ALL

La funzione utente richiede 2 parametri: il codice errore e una stringa descrittiva dell'errore. Da PHP 4.0.2, è possibile opzionalmente fornire altri 3 parametri aggiuntivi: il nome del file, il numero di riga e il contesto dove è avvenuto l'errore (un array che punto alla tabella dei simboli attiva nel punto in cui è avvenuto l'errore).

L'esempio sottostante mostra la gestione delle eccezioni interne attivando gli errori e gestendoli tramite una funzione definita dall'utente:
Esempio 1. Gestione errori con set_error_handler() e trigger_error()
<?php // ridefinisce la costante dell'errore utente - solo PHP 4 define (FATAL,E_USER_ERROR); define (ERROR,E_USER_WARNING); define (WARNING,E_USER_NOTICE); // configura il livello di restituzione errore per questo script error_reporting (FATAL | ERROR | WARNING); // funzione di gestione dell'errore function myErrorHandler ($errno, $errstr, $errfile, $errline) { switch ($errno) { case FATAL: echo "<b>FATAL</b> [$errno] $errstr<br>\n"; echo " Fatal error in line ".$errline." of file ".$errfile; echo ", PHP ".PHP_VERSION." (".PHP_OS.")<br>\n"; echo "Aborting...<br>\n"; exit 1; break; case ERROR: echo "<b>ERROR</b> [$errno] $errstr<br>\n"; break; case WARNING: echo "<b>WARNING</b> [$errno] $errstr<br>\n"; break; default: echo "Unkown error type: [$errno] $errstr<br>\n"; break; } } // funzione di prova del gestore di errore 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", FATAL); if (!is_array($vect)) { trigger_error("Incorrect input vector, array of values expected", ERROR); return null; } for ($i=0; $i<count($vect); $i++) { if (!is_numeric($vect[$i])) trigger_error("Value at position $i is not a number, using 0 (zero)", WARNING); $temp[$i] = log($scale) * $vect[$i]; } return $temp; } // configura il gestore dell'errore definito dall'utente $old_error_handler = set_error_handler("myErrorHandler"); // attiva alcuni errori, definendo prima un array misto con elementi non numerici echo "vector a\n"; $a = array(2,3,"foo",5.5,43.3,21.11); print_r($a); // genera il secondo array, generando un avviso echo "----\nvector b - a warning (b = log(PI) * a)\n"; $b = scale_by_log($a, M_PI); print_r($b); // questo è il problema, passiamo una stringa al posto di un array echo "----\nvector c - an error\n"; $c = scale_by_log("not array",2.3); var_dump($c); // errore critico, il log di zero o di un numero negativo non è definito echo "----\nvector d - fatal error\n"; $d = scale_by_log($a, -2.5); ?>
E l'esecuzione di questo script, darà

vector a
Array
(
    [0] => 2
    [1] => 3
    [2] => foo
    [3] => 5.5
    [4] => 43.3
    [5] => 21.11
)
----
vector b - a warning (b = log(PI) * a)
<b>WARNING</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 - an error
<b>ERROR</b> [512] Incorrect input vector, array of values expected<br>
NULL
----
vector d - fatal error
<b>FATAL</b> [256] log(x) for x <= 0 is undefined, you used: scale = -2.5<br>
  Fatal error in line 36 of file trigger_error.php, PHP 4.0.2 (Linux)<br>
Aborting...<br>

E' importante ricordare che il gestore degli errori standard di PHP viene completamente saltato. La configurazione di error_reporting() non avrà effetto e il vostro gestore di errore sarà richiamato senza considerarla - in ogni caso sarà possibile leggere il valore corrente di error_reporting() ed agire di conseguenza. E' di particolare rilevanza il fatto che questo valore sarà 0 se la riga che causa l'errore viene precedura dall' operatore di controllo errore @.

Notare anche che è vostra responsabilità definire die() se necessario. Se la funzione di gestione dell'errore ritorna, lo script continerà l'esecuzione con la riga seguente a quella che ha causato l'errore.

Vedere anche error_reporting(), restore_error_handler(), trigger_error(), user_error()

set_exception_handler

(PHP 5)

set_exception_handler -- Imposta una funzione di gestione delle eccezioni definita dall'utente

Descrizione

string set_exception_handler ( callback exception_handler )

Imposta la funzione predefinita per la gestione delle eccezioni se un'eccezione non viene individuata all'interno di un blocco try/catch. L'esecuzione sara' terminata dopo la chiamata della funzione exception_handler.

La funzione exception_handler deve essere definita prima di invocare la funzione set_exception_handler(). A quest'ultima funzione deve essere passato un solo parametro, che consiste nell'eccezione individuata. exception_handler ( object exception )

exception: Nome della funzione da invocare in caso di eccezione non individuata.

Elenco dei parametri

exception_handler: Nome della funzione da invocare in caso di eccezione non individuata.

Valori restituiti

Restituisce la funzione di gestione delle eccezioni definita in precedenza, oppure FALSE in caso di errore. Se non era stata definita in precedenza nessuna funzione di gestione delle eccezioni, viene restituita una stringa vuota.

Esempi

Esempio 1. Esempio di funzione set_exception_handler()
<?php function exception_handler($exception) { echo "Eccezione non individuata: " , $exception->getMessage(), "\n"; } set_exception_handler('exception_handler'); throw new Exception('Uncaught Exception'); echo "Non eseguita\n"; ?>

Vedere anche:

restore_exception_handler(), restore_error_handler(), error_reporting(), information about the callback type, e PHP 5 Exceptions.

trigger_error

(PHP 4 >= 4.0.1, PHP 5)

trigger_error -- Genera un messaggio a livello utente di errore/avviso/avvertimento message

Descrizione

void trigger_error ( string error_msg [, int error_type] )

Utilizzata per attivare una condizione di errore utente, può essere usata in congiunzione con il gestore di errore interno, o con una funzione definita dall'utente che sia configurata per essere il nuovo gestore di errore con (set_error_handler()). Funziona soltanto con la famiglia di costanti E_USER, e punta alla predefinita E_USER_NOTICE.

Questa funzione è utile quando sia necessario generare una particolare risposta ad un'eccezione durante l'esecuzione. Per esempio:

if (assert ($divisor == 0))
   trigger_error ("Cannot divide by zero", E_USER_ERROR);

Nota: Vedere set_error_handler() per un esempio più esplicativo.

Vedere anche error_reporting(), set_error_handler(), restore_error_handler(), user_error()

user_error

(PHP 4, PHP 5)

user_error -- Genera un messaggio di errore/avviso/avvertimento a livello utente

Descrizione

void user_error ( string error_msg [, int error_type] )

Questo è un alias per la funzione trigger_error().

Vedere anche error_reporting(), set_error_handler(), restore_error_handler() e trigger_error()

XXXIII. Exif Functions

Introduzione

With the exif extension you are able to work with image meta data. For example, you may use exif functions to read meta data of pictures taken from digital cameras by working with information stored in the headers of the JPEG and TIFF images.

Requisiti

Your PHP must be compiled in with --enable-exif. PHP does not require any additional library for the exif module. Windows users must also have the mbstring extension enabled.

Installazione

To enable exif-support configure PHP with --enable-exif

Windows users must enable both the php_mbstring.dll and php_exif.dll DLL's in php.ini. The php_mbstring.dll DLL must be loaded before the php_exif.dll DLL so adjust your php.ini accordingly.

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

Exif supports automatically conversion for Unicode and JIS character encodings of user comments when module mbstring is available. This is done by first decoding the comment using the specified characterset. The result is then encoded with another characterset which should match your HTTP output.

Tabella 1. Exif configuration options

Name	Default	Changeable	Changelog
exif.encode_unicode	"ISO-8859-15"	PHP_INI_ALL	Available since PHP 4.3.0.
exif.decode_unicode_motorola	"UCS-2BE"	PHP_INI_ALL	Available since PHP 4.3.0.
exif.decode_unicode_intel	"UCS-2LE"	PHP_INI_ALL	Available since PHP 4.3.0.
exif.encode_jis	""	PHP_INI_ALL	Available since PHP 4.3.0.
exif.decode_jis_motorola	"JIS"	PHP_INI_ALL	Available since PHP 4.3.0.
exif.decode_jis_intel	"JIS"	PHP_INI_ALL	Available since PHP 4.3.0.

Per maggiori dettagli sulle costanti PHP_INI_* vedere Appendice G.

Breve descrizione dei parametri di configurazione.

exif.encode_unicode string: exif.encode_unicode defines the characterset UNICODE user comments are handled. This defaults to ISO-8859-15 which should work for most non Asian countries. The setting can be empty or must be an encoding supported by mbstring. If it is empty the current internal encoding of mbstring is used.
exif.decode_unicode_motorola string: exif.decode_unicode_motorola defines the image internal characterset for Unicode encoded user comments if image is in motorola byte order (big-endian). This setting cannot be empty but you can specify a list of encodings supported by mbstring. The default is UCS-2BE.
exif.decode_unicode_intel string: exif.decode_unicode_intel defines the image internal characterset for Unicode encoded user comments if image is in intel byte order (little-endian). This setting cannot be empty but you can specify a list of encodings supported by mbstring. The default is UCS-2LE.
exif.encode_jis string: exif.encode_jis defines the characterset JIS user comments are handled. This defaults to an empty value which forces the functions to use the current internal encoding of mbstring.
exif.decode_jis_motorola string: exif.decode_jis_motorola defines the image internal characterset for JIS encoded user comments if image is in motorola byte order (big-endian). This setting cannot be empty but you can specify a list of encodings supported by mbstring. The default is JIS.
exif.decode_jis_intel string: exif.decode_jis_intel defines the image internal characterset for JIS encoded user comments if image is in intel byte order (little-endian). This setting cannot be empty but you can specify a list of encodings supported by mbstring. The default is JIS.

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

EXIF_USE_MBSTRING (integer)

The exif_imagetype() lists several related built-in constants.

Sommario
exif_imagetype -- Determine the type of an image
exif_read_data -- Reads the EXIF headers from JPEG or TIFF
exif_tagname -- Get the header name for an index
exif_thumbnail -- Retrieve the embedded thumbnail of a TIFF or JPEG image
read_exif_data -- Alias di exif_read_data()

exif_imagetype

(PHP 4 >= 4.3.0, PHP 5)

exif_imagetype -- Determine the type of an image

Descrizione

int exif_imagetype ( string filename )

exif_imagetype() reads the first bytes of an image and checks its signature.

exif_imagetype() can be used to avoid calls to other exif functions with unsupported file types or in conjunction with $_SERVER['HTTP_ACCEPT'] to check whether or not the viewer is able to see a specific image in the browser.

Elenco dei parametri

filename: The image being checked.

Valori restituiti

When a correct signature is found, the appropriate constant value will be returned otherwise the return value is FALSE. The return value is the same value that getimagesize() returns in index 2 but exif_imagetype() is much faster.

Log delle modifiche

Versione	Descrizione
4.3.2	Support for JPC, JP2, JPX, JB2, XBM, and WBMP
4.3.0	Support for SWC

Costanti predefinite

The following constants are defined, and represent possible exif_imagetype() return values:

Tabella 1. Imagetype Constants

Value	Constant
1	`IMAGETYPE_GIF`
2	`IMAGETYPE_JPEG`
3	`IMAGETYPE_PNG`
4	`IMAGETYPE_SWF`
5	`IMAGETYPE_PSD`
6	`IMAGETYPE_BMP`
7	`IMAGETYPE_TIFF_II` (intel byte order)
8	`IMAGETYPE_TIFF_MM` (motorola byte order)
9	`IMAGETYPE_JPC`
10	`IMAGETYPE_JP2`
11	`IMAGETYPE_JPX`
12	`IMAGETYPE_JB2`
13	`IMAGETYPE_SWC`
14	`IMAGETYPE_IFF`
15	`IMAGETYPE_WBMP`
16	`IMAGETYPE_XBM`

Esempi

Esempio 1. exif_imagetype() example
<?php if (exif_imagetype('image.gif') != IMAGETYPE_GIF) { echo 'The picture is not a gif'; } ?>

Vedere anche:

getimagesize()

exif_read_data

(PHP 4 >= 4.2.0, PHP 5)

exif_read_data -- Reads the EXIF headers from JPEG or TIFF

Descrizione

array exif_read_data ( string filename [, string sections [, bool arrays [, bool thumbnail]]] )

exif_read_data() reads the EXIF headers from a JPEG or TIFF image file. This way you can read meta data generated by digital cameras.

Exif headers tend to be present in JPEG/TIFF images generated by digital cameras, but unfortunately each digital camera maker has a different idea of how to actually tag their images, so you can't always rely on a specific Exif header being present.

Height and Width are computed the same way getimagesize() does so their values must not be part of any header returned. Also, html is a height/width text string to be used inside normal HTML.

When an Exif header contains a Copyright note, this itself can contain two values. As the solution is inconsistent in the Exif 2.10 standard, the COMPUTED section will return both entries Copyright.Photographer and Copyright.Editor while the IFD0 sections contains the byte array with the NULL character that splits both entries. Or just the first entry if the datatype was wrong (normal behaviour of Exif). The COMPUTED will also contain the entry Copyright which is either the original copyright string, or a comma separated list of the photo and editor copyright.

The tag UserComment has the same problem as the Copyright tag. It can store two values. First the encoding used, and second the value itself. If so the IFD section only contains the encoding or a byte array. The COMPUTED section will store both in the entries UserCommentEncoding and UserComment. The entry UserComment is available in both cases so it should be used in preference to the value in IFD0 section.

exif_read_data() also validates EXIF data tags according to the EXIF specification (http://exif.org/Exif2-2.PDF, page 20).

Nota: Windows ME/XP can both wipe the Exif headers when connecting to a camera. More information available at http://www.canon.co.jp/Imaging/NOTICE/011214-e.html.

Elenco dei parametri

filename

The name of the image file being read. This cannot be an URL.

sections

Is a comma separated list of sections that need to be present in file to produce a result array. If none of the requested sections could be found the return value is FALSE.

FILE	FileName, FileSize, FileDateTime, SectionsFound
COMPUTED	html, Width, Height, IsColor, and more if available. Height and Width are computed the same way getimagesize() does so their values must not be part of any header returned. Also, html is a height/width text string to be used inside normal HTML.
ANY_TAG	Any information that has a Tag e.g. IFD0, EXIF, ...
IFD0	All tagged data of IFD0. In normal imagefiles this contains image size and so forth.
THUMBNAIL	A file is supposed to contain a thumbnail if it has a second IFD. All tagged information about the embedded thumbnail is stored in this section.
COMMENT	Comment headers of JPEG images.
EXIF	The EXIF section is a sub section of IFD0. It contains more detailed information about an image. Most of these entries are digital camera related.

arrays

Specifies whether or not each section becomes an array. The sections COMPUTED, THUMBNAIL, and COMMENT always become arrays as they may contain values whose names conflict with other sections.

thumbnail

When set to TRUE the thumbnail itself is read. Otherwise, only the tagged data is read.

Valori restituiti

It returns an associative array where the array indexes are the header names and the array values are the values associated with those headers. If no data can be returned, exif_read_data() will return FALSE.

Log delle modifiche

Versione	Descrizione
4.3.0	Can read all embedded IFD data including arrays (returned as such). Also the size of an embedded thumbnail is returned in a `THUMBNAIL` subarray, and can return thumbnails in TIFF format. Also, there is no longer a maximum length for returned values (not until the memory limit has been reached)
4.3.0	If PHP has mbstring support, the user comment can automatically change encoding. Also, if the user comment uses Unicode or JIS encoding this encoding will automatically be changed according to the exif ini settings in `php.ini`
4.3.0	If the image contains any IFD0 data then COMPUTED contains the entry ByteOrderMotorola which is 0 for little-endian (intel) and 1 for big-endian (motorola) byte order. Also, COMPUTED and UserComment no longer only contain the first copyright entry if the datatype was wrong.

Esempi

Esempio 1. exif_read_data() example
<?php echo "test1.jpg:<br />\n"; $exif = exif_read_data('tests/test1.jpg', 'IFD0'); echo $exif===false ? "No header data found.<br />\n" : "Image contains headers<br />\n"; $exif = exif_read_data('tests/test2.jpg', 0, true); echo "test2.jpg:<br />\n"; foreach ($exif as $key => $section) { foreach ($section as $name => $val) { echo "$key.$name: $val<br />\n"; } } ?>
The first call fails because the image has no header information.
Il precedente esempio visualizzerà qualcosa simile a:
test1.jpg: No header data found. test2.jpg: FILE.FileName: test2.jpg FILE.FileDateTime: 1017666176 FILE.FileSize: 1240 FILE.FileType: 2 FILE.SectionsFound: ANY_TAG, IFD0, THUMBNAIL, COMMENT COMPUTED.html: width="1" height="1" COMPUTED.Height: 1 COMPUTED.Width: 1 COMPUTED.IsColor: 1 COMPUTED.ByteOrderMotorola: 1 COMPUTED.UserComment: Exif test image. COMPUTED.UserCommentEncoding: ASCII COMPUTED.Copyright: Photo (c) M.Boerger, Edited by M.Boerger. COMPUTED.Copyright.Photographer: Photo (c) M.Boerger COMPUTED.Copyright.Editor: Edited by M.Boerger. IFD0.Copyright: Photo (c) M.Boerger IFD0.UserComment: ASCII THUMBNAIL.JPEGInterchangeFormat: 134 THUMBNAIL.JPEGInterchangeFormatLength: 523 COMMENT.0: Comment #1. COMMENT.1: Comment #2. COMMENT.2: Comment #3end THUMBNAIL.JPEGInterchangeFormat: 134 THUMBNAIL.Thumbnail.Height: 1 THUMBNAIL.Thumbnail.Height: 1

Vedere anche:

exif_thumbnail()

getimagesize()

exif_tagname

(PHP 4 >= 4.2.0, PHP 5)

exif_tagname -- Get the header name for an index

Descrizione

string exif_tagname ( string index )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Elenco dei parametri

index: The image index

Valori restituiti

Returns the header name, or FALSE if index is undefined.

Vedere anche:

exif_imagetype()

exif_thumbnail

(PHP 4 >= 4.2.0, PHP 5)

exif_thumbnail -- Retrieve the embedded thumbnail of a TIFF or JPEG image

Descrizione

string exif_thumbnail ( string filename [, int &width [, int &height [, int &imagetype]]] )

exif_thumbnail() reads the embedded thumbnail of a TIFF or JPEG image.

If you want to deliver thumbnails through this function, you should send the mimetype information using the header() function.

It is possible that exif_thumbnail() cannot create an image but can determine its size. In this case, the return value is FALSE but width and height are set.

Elenco dei parametri

filename: The name of the image file being read. This image contains an embedded thumbnail.
width: The return width of the returned thumbnail.
height: The returned height of the returned thumbnail.
imagetype: The returned image type of the returned thumbnail. This is either TIFF or JPEG.

Valori restituiti

Returns the embedded thumbnail, or FALSE if the image contains no thumbnail.

Log delle modifiche

Versione	Descrizione
4.3.0	The optional parameters `width`, `height`, and `imagetype` all became available.
4.3.0	May return thumbnails in the TIFF format.

Esempi

Esempio 1. exif_thumbnail() example
<?php if (array_key_exists('file', $_REQUEST)) { $image = exif_thumbnail($_REQUEST['file'], $width, $height, $type); } else { $image = false; } if ($image!==false) { header('Content-type: ' .image_type_to_mime_type($type)); echo $image; exit; } else { // no thumbnail available, handle the error here echo 'No thumbnail available'; } ?>

Vedere anche:

exif_read_data()

image_type_to_mime_type()

read_exif_data

(PHP 4 >= 4.0.1, PHP 5)

read_exif_data -- Alias di exif_read_data()

Descrizione

This function is an alias of: exif_read_data().

XXXIV. Expect Functions

Introduzione

This extension allows to interact with processes through PTY. You may consider using the expect:// wrapper with the filesystem functions which provide a simpler and more intuitive interface.

Requisiti

This module uses the functions of the expect library. You need libexpect version >= 5.43.0.

Installazione

In PHP 4 this PECL extensions source can be found in the ext/ directory within the PHP source or at the PECL link above. In order to use these functions you must compile PHP with expect support by using the --with-expect[=DIR] configure option.

Windows users will enable php_expect.dll inside of php.ini in order to use these functions. In PHP 4 this DLL resides in the extensions/ directory within the PHP Windows binaries download. You may download this PECL extension DLL from the PHP Downloads page or at http://snaps.php.net/.

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

In order to configure expect extension, there are configuration options in the configuration file php.ini.

Tabella 1. Expect Opioni di configurazione

Nome	Default	Modificabile
expect.timeout	"10"	PHP_INI_ALL
expect.loguser	"On"	PHP_INI_ALL
expect.logfile	""	PHP_INI_ALL

Per maggiori dettagli sulle costanti PHP_INI_* vedere Appendice G.

Breve descrizione dei parametri di configurazione.

expect.timeout integer

The timeout period for waiting for the data, when using the expect_expectl() function.

A value of "-1" disables a timeout from occurring.

Nota: A value of "0" causes the expect_expectl() function to return immediately.

expect.loguser boolean

Whether expect should send any output from the spawned process to stdout. Since interactive programs typically echo their input, this usually suffices to show both sides of the conversation.

expect.logfile string

Name of the file, where the output from the spawned process will be written. If this file doesn't exist, it will be created.

Nota: If this configuration is not empty, the output is written regardless of the value of expect.loguser.

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

EXP_GLOB (integer): Indicates that the pattern is a glob-style string pattern.
EXP_EXACT (integer): Indicates that the pattern is an exact string.
EXP_REGEXP (integer): Indicates that the pattern is a regexp-style string pattern.
EXP_EOF (integer): Value, returned by expect_expectl(), when EOF is reached.
EXP_TIMEOUT (integer): Value, returned by expect_expectl() upon timeout of seconds, specified in value of expect.timeout
EXP_FULLBUFFER (integer): Value, returned by expect_expectl() if no pattern have been matched.

Esempi

This example connects to the remote host via SSH, and prints the remote uptime.

Esempio 1. Expect Usage Example

<?php
ini_set ("expect.loguser", "Off");

$stream = popen ("expect://ssh root@remotehost uptime", "r");

$cases = array (
  array (0 => "password:", 1 => PASSWORD)
);

switch (expect_expectl ($stream, $cases))
{
 case PASSWORD:
  fwrite ($stream, "password\n");
  break;
 
 default:
  die ("Error was occurred while connecting to the remote host!\n");
}

while ($line = fgets ($stream)) {
  print $line;
}
fclose ($stream);
?>

Sommario
expect_expectl -- Waits until the output from a process matches one of the patterns, a specified time period has passed, or an EOF is seen
expect_popen -- Exectute command via Bourne shell, and open the PTY stream to the process

expect_expectl

(no version information, might be only in CVS)

expect_expectl -- Waits until the output from a process matches one of the patterns, a specified time period has passed, or an EOF is seen

Descrizione

mixed expect_expectl ( resource expect, array cases )

Waits until the output from a process matches one of the patterns, a specified time period has passed, or an EOF is seen.

Elenco dei parametri

expect

An Expect stream, previously opened with expect_popen().

cases

An array of expect cases. Each expect case is an indexed array, as described in the following table:

Tabella 1. Expect Case Array

Index Key	Value Type	Description	Is Mandatory	Default Value
0	string	pattern, that will be matched against the output from the stream	yes
1	mixed	value, that will be returned by this function, if the pattern matches	yes
2	integer	pattern type, one of: `EXP_GLOB`, `EXP_EXACT` or `EXP_REGEXP`	no	`EXP_GLOB`

Valori restituiti

Returns value associated with the pattern that was matched.

On failure this function returns: EXP_EOF, EXP_TIMEOUT or EXP_FULLBUFFER

Esempi

Esempio 1. expect_expectl() example
<?php // Copies file from remote host: ini_set ("expect.timeout", 30); $stream = popen ("expect://scp user@remotehost:/var/log/messages /home/user/messages.txt", "r"); $cases = array ( array (0 => "password:", 1 => PASSWORD), array (0 => "yes/no)?", 1 => YESNO) ); while (true) { switch (expect_expectl ($stream, $cases)) { case PASSWORD: fwrite ($stream, "password\n"); break; case YESNO: fwrite ($stream, "yes\n"); break; case EXP_TIMEOUT: case EXP_EOF: break 2; default: die ("Error has occurred!\n"); } } fclose ($stream); ?>

Vedere anche:

expect_popen()

expect_popen

(no version information, might be only in CVS)

expect_popen -- Exectute command via Bourne shell, and open the PTY stream to the process

Descrizione

resource expect_popen ( string command )

Execute command via Bourne shell, and open the PTY stream to the process.

Elenco dei parametri

command: Command to execute.

Valori restituiti

Returns an open PTY stream to the process'es stdio, stdout and stderr.

On failure this function returns FALSE.

Esempi

Esempio 1. expect_popen() example
<?php // Login to the PHP.net CVS repository: $stream = expect_popen ("cvs -d :pserver:anonymous@cvs.php.net:/repository login"); sleep (3); fwrite ($stream, "phpfi\n"); fclose ($stream); ?>

Vedere anche:

popen()

XXXV. File Alteration Monitor Functions

Introduzione

FAM monitors files and directories, notifying interested applications of changes. More information about FAM is available at http://oss.sgi.com/projects/fam/.

A PHP script may specify a list of files for FAM to monitor using the functions provided by this extension.

The FAM process is started when the first connection from any application to it is opened. It exits after all connections to it have been closed.

Nota: Questo modulo è stato spostato nel repository PECL e non sarà più rilascio con il PHP dalla versione 5.1.0.

Nota: Questo modulo non è disponibile su piattaforme Windows.

Requisiti

This extension uses the functions of the FAM library, developed by SGI. Therefore you have to download and install the FAM library.

Installazione

To use PHP's FAM support you must compile PHP --with-fam[=DIR] where DIR is the location of the directory containing the lib and include directories.

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Tipi di risorse

FAM resource

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

Tabella 1. FAM event constants

Constant	Description
`FAMChanged` (integer)	Some value which can be obtained with fstat(1) changed for a file or directory.
`FAMDeleted` (integer)	A file or directory was deleted or renamed.
`FAMStartExecuting` (integer)	An executable file started executing.
`FAMStopExecuting` (integer)	An executable file that was running finished.
`FAMCreated` (integer)	A file was created in a directory.
`FAMMoved` (integer)	This event never occurs.
`FAMAcknowledge` (integer)	An event in response to fam_cancel_monitor().
`FAMExists` (integer)	An event upon request to monitor a file or directory. When a directory is monitored, an event for that directory and every file contained in that directory is issued.
`FAMEndExist` (integer)	Event after the last FAMEExists event.

Sommario
fam_cancel_monitor -- Terminate monitoring
fam_close -- Close FAM connection
fam_monitor_collection -- Monitor a collection of files in a directory for changes
fam_monitor_directory -- Monitor a directory for changes
fam_monitor_file -- Monitor a regular file for changes
fam_next_event -- Get next pending FAM event
fam_open -- Open connection to FAM daemon
fam_pending -- Check for pending FAM events
fam_resume_monitor -- Resume suspended monitoring
fam_suspend_monitor -- Temporarily suspend monitoring

bool fam_suspend_monitor ( resource fam, resource fam_monitor )

fam_suspend_monitor() temporarily suspend monitoring of a resource previously requested using one of the fam_monitor_ functions. Monitoring can later be continued using fam_resume_monitor() without the need of requesting a complete new monitor.

XXXVI. Funzioni Forms Data Format

Introduzione

Il Forms Data Format (FDF) è un formato per la gestione di form all'interno di documenti PDF. Si dovrebbe leggere la documentazione al link http://partners.adobe.com/asn/acrobat/forms.jsp per avere maggiori informazioni su cosa sia FDF e su come usarlo in generale.

L'idea di base è che FDF sia simile ai form HTML. Fondamentalmente la differenza consiste nel formato con cui i dati sono inviati al server quando viene premuto il bottone di sottomissione del form (che, ovviamente, è in Form Data Format) e il formato del form stesso (che è il Portable Document Format, PDF). L'elaborazione dei dati FDF è una delle caratteristiche delle funzioni fdf.Ma ve ne sono altre. Una di queste consiste nel prendere un form PDF e compilarne i campi senza modificare il form . In questo caso si dovrebbe creare il documento FDF (fdf_create()) impostare i valori per ciascun campo (fdf_set_value()) e associarlo al form PDF (fdf_set_file()). Infine viene inviato al browser browser con MimeType application/vnd.fdf. Acrobat Reader riconosce il MimeType, legge il form PDF associato e completa i campi con i dati dal documento FDF.

Se si apre un documento FDF con un editor di testo si troveranno degli oggetti con nome FDF. Tali oggetti possono contenere diversi campi tipo Fields, F, Status etc.. I campi più comuni sono Fields che puntano alla lista dei campi di input, e F che contiene il nome del file PDF a cui appartengono questi dati. Questi campi sono definiti dalla documentazione FDF come chiave /F (/F-Key) e chiave /Status (/Status-Key) Le modifiche a questi chiavi posso essere svolte con funzioni tipo fdf_set_file() e fdf_set_status(). I campi sono modificati dalle funzioni fdf_set_value(), fdf_set_opt() etc..

Requisiti

Occorre avere disponibile il toolkit FDF SDK, scaricabile da http://partners.adobe.com/asn/acrobat/forms.jsp. Dal PHP 4.3 occorre avere almeno l'SDK versione 5.0. Le librerie FDF sono disponibili in formato binario solo per le piattaforme supportate da Adobe quali Win32, Linux, Solaris e AIX.

Installazione

Occorre compilare il PHP con --with-fdftk[=DIR].

Nota: Se si hanno problemi nella configurazione del PHP con supporto fdftk, verificare che i file fdftk.h e libfdftk.so siano nel posto corretto. Lo script di configurazione supporta sia la struttura delle directory della distribuzione FDFSDK, sia l'usuale struttura DIR/include / DIR/lib, pertanto si può puntare o direttamente alla directory della distribuzione decompressa o posizionare il file con l'header e la libreria appropriata per la piattaforma, ad es. /usr/local/include e /usr/local/lib ed eseguire configure con --with-fdftk=/usr/local.

Nota per gli utenti Win32: Per potere abilitare questo modulo sui sistemi Windows, occorre copiare fdftk.dll dalla cartella DLL del rilascio PHP7Win32 alla cartella SYSTEM32 della macchina Windows. (Es. C:\WINNT\SYSTEM32 oppure C:\WINDOWS\SYSTEM32).

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Tipi di risorse

fdf

La maggior parte delle funzioni richiedono una risorsa fdf come primo parametro. La risorsa fdf è un puntatore al file fdf aperto. Le risorse fdf possono essere ottenute dalle funzioni fdf_create(), fdf_open() e fdf_open_string().

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

FDFValue (integer)
FDFStatus (integer)
FDFFile (integer)
FDFID (integer)
FDFFf (integer)
FDFSetFf (integer)
FDFClearFf (integer)
FDFFlags (integer)
FDFSetF (integer)
FDFClrF (integer)
FDFAP (integer)
FDFAS (integer)
FDFAction (integer)
FDFAA (integer)
FDFAPRef (integer)
FDFIF (integer)
FDFEnter (integer)
FDFExit (integer)
FDFDown (integer)
FDFUp (integer)
FDFFormat (integer)
FDFValidate (integer)
FDFKeystroke (integer)
FDFCalculate (integer)
FDFNormalAP (integer)
FDFRolloverAP (integer)
FDFDownAP (integer)

Esempi

Il seguente esempio illustra l'elaborazione dei dati di un form.
Esempio 1. Elaborazione di un documento FDF
<?php // Apre fdf dalla stringa di input fornita dalla estensione // Il form pdf contiene diversi campi con nome // volume, date, comment, publisher, preparer, e due checkboxes // show_publisher e show_preparer. $fdf = fdf_open_string($HTTP_FDF_DATA); $volume = fdf_get_value($fdf, "volume"); echo "TIl campo volume ha valore '<b>$volume</b>'<br />"; $date = fdf_get_value($fdf, "date"); echo "Il campo date ha valore '<b>$date</b>'<br />"; $comment = fdf_get_value($fdf, "comment"); echo "Il campo commento ha valore '<b>$comment</b>'<br />"; if (fdf_get_value($fdf, "show_publisher") == "On") { $publisher = fdf_get_value($fdf, "publisher"); echo "Il campo publisher ha valore '<b>$publisher</b>'<br />"; } else echo "Publisher non deve essere visualizzato.<br />"; if (fdf_get_value($fdf, "show_preparer") == "On") { $preparer = fdf_get_value($fdf, "preparer"); echo "Il campo preparer ha valore '<b>$preparer</b>'<br />"; } else echo "Preparer non deve essere visualizzato.<br />"; fdf_close($fdf); ?>

Sommario
fdf_add_doc_javascript -- Aggiunge codice Javascript ad un documento FDF
fdf_add_template -- aggiunge un templat in un documento FDF
fdf_close -- Chiude un documento FDF
fdf_create -- Crea un nuovo documento FDF
fdf_enum_values -- Richiama una funzione definita dall'utente per ciascun valore del documento
fdf_errno -- Restituisce il codice di errore per l'ultima operazione FDF
fdf_error -- Restituisce la descrizione di un codice di errore fdf
fdf_get_ap -- Ottiene il formato di un campo
fdf_get_attachment -- Estrae file racchiusi nel FDF
fdf_get_encoding -- Restituisce il valore della chiave /Encoding
fdf_get_file -- Ottiene il valore della chiave /F
fdf_get_flags -- Ottiene i flag di un campo
fdf_get_opt -- Ottiene un valore dalla matrice delle opzioni di un campo
fdf_get_status -- Restituisce il valore per la chiave /STATUS
fdf_get_value -- Ottiene il valore di un campo
fdf_get_version -- Restituisce il numero di versione per le API FDF o un file
fdf_header -- Imposta gli header specifici per FDF
fdf_next_field_name -- Restituisce il nome del campo successivo
fdf_open_string -- Legge un documento FDF da una stringa
fdf_open -- Apre un documento FDF
fdf_remove_item -- Imposta il frame di destinazione per un form
fdf_save_string -- Restituisce un documento FDF come una stringa
fdf_save -- Salva un documento FDF
fdf_set_ap -- Imposta l'apparire di un campo
fdf_set_encoding -- Imposta la codifica dei caratteri per FDF
fdf_set_file -- Imposta un documento PDF per visualizzare i dati FDF presenti
fdf_set_flags -- Imposta i flag di un campo
fdf_set_javascript_action -- Imposta un'azione javascript per un campo
fdf_set_on_import_javascript -- Adds javascript code to be executed when Acrobat opens the FDF
fdf_set_opt -- Imposta le opzioni per un campo
fdf_set_status -- Imposta il valore per la chiave /STATUS
fdf_set_submit_form_action -- Imposta un'azione per un campo nell'invio di un form
fdf_set_target_frame -- Imposta il frame in cui visualizzare il form
fdf_set_value -- Imposta il valore di un campo
fdf_set_version -- Imposta il numero di versione per un file FDF

fdf_get_attachment

(PHP 4 >= 4.3.0, PHP 5)

fdf_get_attachment -- Estrae file racchiusi nel FDF

Descrizione

array fdf_get_attachment ( resource fdf_document, string fieldname, string savepath )

La funzione estrae un file indicato dal "selettore di file" fieldname e lo memorizza in savepath. Il parametro savepath può essere il nome di file o una directory esistente nella quale verrà creato il file con il suo nome originale. Eventuali file con il medesimo nome saranno sovrascritti.

Nota: Sembra che non ci sia altro metodo per risalire al nome originale del file se non quello di scaricare il file nella directory indicata da savepath e rilevare il nome con cui viene scritto.

La matrice restituita contiene i seguenti indici:

path - percorso in cui viene archiviato il file
size - dimensione del file in bytes
type - mimetype se dato nel FDF

Gli elementi di una matrice di campi possono essere recuperati passando il parametro opzionale which, iniziando da zero. Per i campi non matrice il parametro which viene ignorato.

Nota: Il supporto delle matrici ed il campo opzionale which sono stati aggiunti in PHP 4.3.

Vedere anche fdf_set_value().

fdf_get_version

(PHP 4 >= 4.3.0, PHP 5)

fdf_get_version -- Restituisce il numero di versione per le API FDF o un file

Descrizione

string fdf_get_version ( [resource fdf_document] )

Questa funzione restituisce il numero i versione FDF per il dato documento fdf_document, o il numero di versione per il toolkit API, se il parametro viene omesso.

Per il corrente toolkit FDF 5.0 il numero di versione delle API è il '5.0' e il numero di versione del documento può essere '1.2', '1.3' oppure '1.4'.

Vedere anche fdf_set_version().

fdf_header

(PHP 4 >= 4.3.0, PHP 5)

fdf_header -- Imposta gli header specifici per FDF

Descrizione

bool fdf_header ( void )

Questa è una funzione di comodità per impostare le intestazioni HTTP per inviare documenti FDF. La funzione imposta il campo Content-type: a application/vnd.fdf.

fdf_next_field_name

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

fdf_next_field_name -- Restituisce il nome del campo successivo

bool fdf_remove_item ( resource fdfdoc, string fieldname, int item )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

fdf_save_string

(PHP 4 >= 4.3.0, PHP 5)

fdf_save_string -- Restituisce un documento FDF come una stringa

Descrizione

string fdf_save_string ( resource fdf_document )

La funzione fdf_save_string() restituisce il documento FDF come una stringa.

Esempio 1. Recupero di un documento FDF come stringa
<?php $fdf = fdf_create(); fdf_set_value($fdf, "foo", "bar"); $str = fdf_save_string($fdf); fdf_close($fdf); echo $str; ?>
Visualizzerà qualcosa tipo
%FDF-1.2 %âãÏÓ 1 0 obj << /FDF << /Fields 2 0 R >> >> endobj 2 0 obj [ << /T (foo)/V (bar)>> ] endobj trailer << /Root 1 0 R >> %%EOF

Vedere anche: fdf_save(), fdf_open_string(), fdf_create() e fdf_close().

fdf_save

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

fdf_save -- Salva un documento FDF

Descrizione

bool fdf_save ( resource fdf_document [, string filename] )

bool fdf_set_file ( resource fdf_document, string url [, string target_frame] )

La funzione fdf_set_file() selezione un differente documento PDF nel quale visualizzare i dati di un form originati da un'altro. Il parametro url deve essere un URL assoluto.

Il frame nel quale visualizzare il documento può essere impostato tramite il parametro target_frame o tramite la funzione fdf_set_target_frame().

Esempio 1. Passaggio di dati FDF a un secondo form

<?php
  /* imposta il content type a Adobe FDF */
  fdf_header();

  /* inizia un nuovo fdf */
  $fdf = fdf_create();
    
  /* imposta il campo "foo" a "bar" */
  $fdf_set_value($fdf, "foo", "bar");

  /* dice al client di visualizzare i dati fdf in "fdf_form.pdf" */
  fdf_set_file($fdf, "http://www.example.com/fdf_form.pdf");

  /* scrive fdf */
  fdf_save();

  /* chiusura */
  fdf_close();
?>

Nota: Nella vecchia versione del toolkit fdf l'ultimo parametro determinava se il valore del campo doveva essere convertito in un PDF Name (isName = 1) o in una stringa PDF (isName = 0). Questo campo non viene più utilizzato con l'attuale versione 5.0. Per motivi di compatibilità è ancora supportato come parametro opzionale a partire da PHP 4.3, ma viene ignorato.
Il supporto per value come matrice è stato aggiunto in PHP 4.3.

Vedere anche fdf_get_value() e fdf_remove_item().

fdf_set_version

(PHP 4 >= 4.3.0, PHP 5)

fdf_set_version -- Imposta il numero di versione per un file FDF

Descrizione

string fdf_set_version ( resource fdf_document, string version )

Questa funzione imposta il numero di versione del file FDF fdf_document a version. Alcune caratteristiche supportate da questo modulo sono soltatnto disponibili nelle più recenti versioni di fdf. L'attuale toolkit FDF (5.0) accetta come versione i valori '1.2', '1.3' or '1.4'.

Vedere anche fdf_get_version().

XXXVII. Funzioni filePro

Introduzione

Queste funzioni permettono l'accesso in sola lettura dei dati del database filePro.

filePro è un marchio registrato della tecnologia fP Technologies, Inc. Per maggiori informazioni su filePro: http://www.fptech.com/.

Installazione

Il supporto a filePro in PHP non è abilitato per default. Per abilitare la funzioni di sola lettura di filePro occorre impostare il parametro di configurazione --enable-filepro durante la compila del PHP.

Sommario
filepro_fieldcount -- Conta quanti campi sono presenti in un database filePro
filepro_fieldname -- Restituisce il nome di un campo
filepro_fieldtype -- Restituisce il tipo del campo
filepro_fieldwidth -- Restituisce la dimensione di un campo
filepro_retrieve -- Preleva i dati da un database filePro
filepro_rowcount -- Conta quante righe sono presenti in un database filePro
filepro -- Legge e verifica la mappa del file

filepro_fieldcount

(PHP 3, PHP 4, PHP 5)

filepro_fieldcount -- Conta quanti campi sono presenti in un database filePro

Descrizione

int filepro_fieldcount ( void )

string filepro_retrieve ( int row_number, int field_number )

Restituisce dei dati da una locazione specificata nel database. Il parametro row_number deve essere tra zero ed il numero complessivo delle righe meno uno (0..filepro_rowcount() - 1). In modo analogo il parametro field_number accetta valori compresi tra 0 ed il numero complessivo dei campi meno uno (0..filepro_fieldcount() - 1)

Nota: Quando safe-mode è abilitato, PHP controlla che i file o le directory sulle quali si sta andando a lavorare, abbiano lo stesso UID dello script che è in esecuzione.

filepro_rowcount

(PHP 3, PHP 4, PHP 5)

filepro_rowcount -- Conta quante righe sono presenti in un database filePro

Descrizione

int filepro_rowcount ( void )

Restituisce il numero di righe presenti in un database filePro.

Nota: Quando safe-mode è abilitato, PHP controlla che i file o le directory sulle quali si sta andando a lavorare, abbiano lo stesso UID dello script che è in esecuzione.

Vedede anche filepro().

filepro

(PHP 3, PHP 4, PHP 5)

filepro -- Legge e verifica la mappa del file

Descrizione

bool filepro ( string directory )

Questa funzione legge e verifica la mappa del file, immagazzinando l'indice del campo e le informazioni.

Non viene eseguito nessun locking, si dovrebbe evitare di modificare il database filePro mentre quest'ultimo potrebbe venire aperto in PHP.

Nota: Quando safe-mode è abilitato, PHP controlla che i file o le directory sulle quali si sta andando a lavorare, abbiano lo stesso UID dello script che è in esecuzione.

XXXVIII. Filesystem Functions

Introduzione

Requisiti

Non sono richieste librerie esterne per compilare questo modulo, ma se si desidera avere il supporto per LFS (file di grandi dimensioni) su Linux, occorre avere una versione recente di glibc e occorre compilare il PHP con i seguenti parametri: -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64.

Installazione

Non è necessaria nessuna installazione per usare queste funzioni, esse fanno parte del core di PHP.

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

Tabella 1. Opzioni di configurazione per Filesystem e Streams

Nome	Default	Modificabile
allow_url_fopen	"1"	PHP_INI_SYSTEM
user_agent	NULL	PHP_INI_ALL
default_socket_timeout	"60"	PHP_INI_ALL
from	NULL	??
auto_detect_line_endings	"Off"	PHP_INI_ALL

Breve descrizione dei parametri di configurazione.

allow_url_fopen boolean

Questa opzione abilita i wrapper URL per fopen, in modo da potere accedere ad oggetti URL come file. Per default sono forniti wrapper per accedere a file remoti usando il protocollo ftp o http, alcune estensioni, tipo zlib, possono registrarne altri.

Nota: Questa impostazione può essere impostata solamente nel php.ini per motivi di sicurezza.

Nota: Questa opzione è stata aggiunta subito dopo il rilascio di PHP 4.0.3. Per le versioni fino a 4.0.3 compresa si può disabilitare questa opzione solo al momento della compila utilizzando il parametro di configurazione --disable-url-fopen-wrapper.

Avvertimento

Nelle versioni precedenti alla 4.3.0 per i sistemi Windows, le suguenti funzioni non supportano l'accesso a file remoti: include(), include_once(), require(), require_once() e le funzioni imagecreatefromXXX nel modulo Riferimento LVI, Funzioni per le immagini.

user_agent string

Definisce un agente utente il PHP.

default_socket_timeout integer

Timeout di default (in secondi) per gli stream sui socket.

Nota: Questa opzione di configurazione è stata inserita in PHP 4.3.0

from="joe@example.com" string

Imposta la password per l'ftp anonimo (il tuo indirizzo di posta elettronica).

auto_detect_line_endings boolean

Quando è attivato, il PHP esamina i dati letti da fgets() e file() per vedere se si sta utilizzando le convezioni di Unix, MS-Dos o Macintosh.

Questo permette al PHP di operare con sistemi Macintosh, ma, per default, l'opzione è impostata a Off, poichè vi è una piccola penalizzazione di velocità nel cercare di individuare il tipo di EOL per la prima riga; e anche perchè in alcuni casi si è sperimentato che l'utilizzo del carriage-returns come separatore nei sistemi Unix ha generato comportamenti non compatibili con il passato.

Nota: Questa opzione è stata introdotta in PHP 4.3.0

Tipi di risorse

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

GLOB_BRACE (integer)
GLOB_ONLYDIR (integer)
GLOB_MARK (integer)
GLOB_NOSORT (integer)
GLOB_NOCHECK (integer)
GLOB_NOESCAPE (integer)
PATHINFO_DIRNAME (integer)
PATHINFO_BASENAME (integer)
PATHINFO_EXTENSION (integer)
FILE_USE_INCLUDE_PATH (integer)
FILE_APPEND (integer)
FILE_IGNORE_NEW_LINES (integer)
FILE_SKIP_EMPTY_LINES (integer)

Vedere anche:

Vedere anche le sezioni Directory e Esecuzione di programmi.

Per avere un elenco e le spiegazioni sui vari wrapper URL che possono essere utilizzati sui file remoti, vedere Appendice M.

Sommario
basename -- Restituisce il nome del file dal percorso indicato
chgrp -- Cambia il gruppo del file
chmod -- Cambia le impostazioni del file
chown -- Cambia il proprietario del file
clearstatcache -- Libera la cache dello stato di un file
copy -- Copia un file
delete -- Vedere unlink() oppure unset()
dirname -- Restituisce il nome della directory dal percorso indicato
disk_free_space -- Restituisce lo spazio disponibile nella directory
disk_total_space -- Restituisce lo spazio totale di una directory
diskfreespace -- Alias di disk_free_space()
fclose -- Chiude un puntatore a file aperto
feof -- Verifica se è stata raggiunta la fine del file su un puntatore a file
fflush -- Invia l'output in un file
fgetc -- Prende un carattere da un puntatore a file
fgetcsv -- Prende una riga da un puntatore a file e l'analizza in cerca di campi CSV
fgets -- Prende una riga da un puntatore a file
fgetss -- Prende una riga da un puntatore a file ed elimina i tag HTML
file_exists -- Controlla se un file o directory esiste
file_get_contents -- Legge un file all'interno di una stringa
file_put_contents -- Write a string to a file
file -- Legge l'intero file in un vettore
fileatime -- Prende l'ora dell'ultimo accesso al file
filectime -- Prende l'ora in cui l'inode del file è stato modificato
filegroup -- Restituisce il gruppo di un file
fileinode -- Restituisce il numero di inode del file
filemtime -- Restituisce l'ora delle modifiche al file
fileowner -- Restituisce il proprietario del file
fileperms -- Restituisce i permessi sui file
filesize -- Restituisce la dimensione del file
filetype -- Restituisce il tipo di file
flock -- Sistema di bloccaggio file
fnmatch -- Match filename against a pattern
fopen -- Apre un file o un URL
fpassthru -- Invia tutti i dati rimanenti su un puntartore a file
fputcsv -- Format line as CSV and write to file pointer
fputs -- Alias di fwrite()
fread -- Legge un file salvaguardando la corrispondenza binaria
fscanf -- Analizza l'input da un file secondo un determinato formato
fseek -- Sposta un puntatore sul file
fstat -- Restituisce le informazioni riguardanti un file attraverso un puntatore al file aperto
ftell -- Comunica la posizione di lettura/scrittura del puntatore al file
ftruncate -- Tronca un file alla lunghezza data
fwrite -- Scrive un file salvaguardando la corrispondenza binaria
glob -- Find pathnames matching a pattern
is_dir -- Dice se la stringa corrisponde ad una directory
is_executable -- Dice se il file indicato è eseguibile
is_file -- Dice se il file è un file regolare
is_link -- Dice se il file è un link simbolico
is_readable -- Dice se un file è leggibile
is_uploaded_file -- Dice se un file fù caricato via HTTP POST.
is_writable -- Dice se un file è scrivibile
is_writeable -- Alias di is_writable()
link -- Crea un hard link
linkinfo -- Restituisce informazioni su un collegamento
lstat -- Da informazioni su un file o un link simbolico
mkdir -- Crea una directory
move_uploaded_file -- Muove un file caricato in una nuova posizione
parse_ini_file -- Legge il file di configurazione
pathinfo -- Restituisce informazioni su un percorso di file
pclose -- Chiude un puntatore ad un file di processo
popen -- Apre un puntatore ad un file di processo
readfile -- Invia un file
readlink -- Restituisce il target di un link simbolico
realpath -- Restituisce un percorso assoluto regolare
rename -- Rinomina un file o una directory
rewind -- Riavvolge la posizione di un puntatore a file
rmdir -- Rimuove una directory
set_file_buffer -- Alias di stream_set_write_buffer()
stat -- Da informazioni su un file
symlink -- Crea un link simbolico
tempnam -- Crea file con unico nome file
tmpfile -- Crea un file temporaneo
touch -- Imposta l'ora di modifica di un file
umask -- Cambia l'umask corrente
unlink -- Cancella un file

basename

(PHP 3, PHP 4, PHP 5)

basename -- Restituisce il nome del file dal percorso indicato

Descrizione

string basename ( string path [, string suffix] )

Data una stringa contenente il percorso di un file, questa funzione restituisce il nome del file. Se il nome del file finisce in suffix quest'ultimo verrà tagliato.

Su Windows, sia gli slash (/) che i backslash (\) vengono utilizzati come carattere di separazione delle directory. In altri ambienti, si usa solo lo slash semplice (/).

Esempio 1. Esempio di basename()
<?php $path = "/home/httpd/html/index.php"; $file = basename($path); // la variabile $file contiene "index.php" $file = basename($path,".php"); // la variabile $file contiene "index" ?>

Nota: Il parametro suffix è stato aggiunto in PHP 4.1.0.

Vedere anche dirname()

chgrp

(PHP 3, PHP 4, PHP 5)

chgrp -- Cambia il gruppo del file

Descrizione

bool chgrp ( string filename, mixed group )

Tenta di cambiare il gruppo del file filename in group (specificato per nome o numero). Solo l'amministratore può cambiare arbitrariamente il gruppo di un file; gli altri utenti possono cambiare il gruppo dei file solo fra gruppi di cui sono membri.

Restituisce TRUE se ha successo; FALSE altrimenti.

Nota: Questa funzione non è eseguibile con file remoti, ma con file accessibili attraverso il filesystem del server.

Nota: Quando safe-mode è abilitato, PHP controlla che i file o le directory sulle quali si sta andando a lavorare, abbiano lo stesso UID dello script che è in esecuzione.

Vedere anche chown() e chmod().

chmod

(PHP 3, PHP 4, PHP 5)

chmod -- Cambia le impostazioni del file

Descrizione

bool chmod ( string filename, int mode )

Tenta di cambiare le impostazioni del file filename in quelle date in mode.

Si osservi che mode non viene automaticamente assunto come valore ottale, per cui le stringhe (come "g+w") non verranno elaborate correttamente. Per ottenere l'operazione desiderata, è necessario far precedere mode da uno zero (0):

<?php
chmod("/somedir/somefile", 755);   // decimale; probabilmente errato   
chmod("/somedir/somefile", "u+rwx,go+rx"); // stringa; errato       
chmod("/somedir/somefile", 0755);  // ottale; valore corretto di mode (preceduto da uno 0)
?>

Il parametro mode consiste in tre numeri ottali costituenti le restrizioni dell'accesso per il proprietario, il gruppo utente a cui appartiene il proprietario, e gli altri utenti, nell'ordine dato. Ciascun numero può essere calcolato aggiungendo i permessi al valore base per l'utente. Il numero 1 indica che si abilita all'esecuzione del file, con il numero 2 si assegnano i diritti di scrittura, con il numero 4 si assegna il permesso di lettura del file. Aggiungere questi numeri per ottenere i diritti richiesti. Si possono avere maggiori dettagli sui permessi dei sistemi Unix usando il comando 'man 1 chmod' e 'man 2 chmod'.

<?php
// Lettura e scrittura per il proprietario, e nessun permesso per gli altri
chmod("/somedir/somefile", 0600);

// Lettura e scrittura per il proprietario, e lettura per gli altri
chmod("/somedir/somefile", 0644);

// Accesso completo per il proprietario, e lettura ed esecuzione per gli altri
chmod("/somedir/somefile", 0755);

// Accesso completo per il proprietario, e lettura ed esecuzione per il gruppo del proprietario
chmod("/somedir/somefile", 0750);
?>

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Nota: L'utente corrente è l'utente con il quale viene eseguito il PHP. Probabilmente non è il medesimo utente che si usa da shell o dall'accesso FTP.

Nota: Questa funzione non è eseguibile con file remoti, ma con file accessibili attraverso il filesystem del server.

Nota: Quando modalità sicura viene abilitato, PHP controlla se i files o le directory su cui si sta operando, hanno il medesimo UID (proprietario) dello script che sta per essere eseguito. In aggiunta, non si può impostare il SUID, SGID e sticky bit.

Vedere anche chown() e chgrp().

chown

(PHP 3, PHP 4, PHP 5)

chown -- Cambia il proprietario del file

Descrizione

bool chown ( string filename, mixed user )

Tenta di cambiare il proprietario di un file filename in user (specificato per nome o numero). Solo l'amministratore può cambiare il proprietario di un file.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Nota: Questa funzione non è eseguibile con file remoti, ma con file accessibili attraverso il filesystem del server.

Nota: Quando safe-mode è abilitato, PHP controlla che i file o le directory sulle quali si sta andando a lavorare, abbiano lo stesso UID dello script che è in esecuzione.

Vedere anche chown() e chmod().

clearstatcache

(PHP 3, PHP 4, PHP 5)

clearstatcache -- Libera la cache dello stato di un file

Descrizione

void clearstatcache ( void )

Quando si eseguono le funzioni di sistema stat o lstat o una delle funzioni elencate nella lista delle funzioni coinvolte (vedi sotto), il PHP memorizza le informazioni restituite da queste funzioni in modo da fornire migliori performance. Esistono, tuttavia, casi in cui si desidera rimuovere le informazioni memorizzate. Ad esempio, nel caso in cui un file venga controllato più volte nel medesimo script ed il file si trova in situazioni in cui possa venire rimosso o possa essere variato durante l'esecuzione dello script; in questi casi si può volere cancellare le informazioni memorizzate. Per queste situazioni si può utilizzare la funzione clearstatcache() che cancella le informazioni memorizzate dal PHP sullo stato di un file.

Occorre notare che il PHP non memorizza informazioni su file inesistenti. Pertanto se si esegue la funzione file_exists() su un file che non esiste, questa restituisce FALSE fino a quando il file non viene creato. Un volta ccreato il file, la funzione restituisce TRUE anche se il file viene cancellato.

Nota: Queste funzioni memorizzano informazioni su specifici file, pertanto basta eseguire clearstatcache() nel caso di molteplici operazioni sul medesimo file oppure nel caso sia necessario non memorizzare informazioni su un dato file.

Tale valore viene memorizzato solo per la durata di una singola richiesta.

Le funzioni coinvolte sono stat(), lstat(), file_exists(), is_writable(), is_readable(), is_executable(), is_file(), is_dir(), is_link(), filectime(), fileatime(), filemtime(), fileinode(), filegroup(), fileowner(), filesize(), filetype() e fileperms().

copy

(PHP 3, PHP 4, PHP 5)

copy -- Copia un file

Descrizione

bool copy ( string source, string dest )

Copia il file source in dest. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.
Esempio 1. copy() example
<?php $file = 'example.txt'; $newfile = 'example.txt.bak'; $file = 'example.txt'; $newfile = 'example.txt.bak'; if (!copy($file, $newfile)) { echo "Copia di $file non riuscita ...\n"; } ?>

Nota: Come da PHP 4.3.0, sia source che dest potrebbero essere URL se "fopen wrappers" è stato abilitato. Vedere fopen() per ulteriori dettagli. Se il parametro dest punta ad un URL, l'operazione di copia potrebbe fallire se il wrapper non supporta la sovrascrittura di file esistenti.

Avvertimento

Se il file di destinazione già esiste, esso verrà sovrascritto.

Nota: Nota di compatibilità con Windows: se viene copiato un file vuoto, copy() restituisce falso, ma il file sarà copiato correttamente.

Vedere anche move_uploaded_file(), rename(), e la sezione del manuale riguardo handling file uploads.

delete

(no version information, might be only in CVS)

delete -- Vedere unlink() oppure unset()

Descrizione

void delete ( string file )

Questa funzione non esiste, la sua presenza nel manuale vuole essere utile a coloro che cercano nel posto sbagliato le funzioni unlink() o unset().

Vedere anche unlink() per cancellare file, unset() per eliminare variabili.

dirname

(PHP 3, PHP 4, PHP 5)

dirname -- Restituisce il nome della directory dal percorso indicato

Descrizione

string dirname ( string path )

Data una stringa contenente il percorso di un file, questa funzione restituirà il nome della directory.

Su windows sia gli slash (/) che i backslash (\) vengono utilizzati come caratteri di separazione nei percorsi. In altri ambienti, c'è solo lo slash in avanti (/).

Esempio 1. dirname() example
<?php $path = "/etc/passwd"; $file = dirname($path); // $file contiene "/etc" ?>

Nota: In PHP 4.0.3, la funzione dirname() è stata modificata per essere conforme alle specifiche POSIX. Essenzialmente ciò significa che non ci sono slash nel parametro path , viene restituito un punto ('.') per indicare la directory corrente. In altro modo, la stringa restituita è path senza alcun /component. Occorre notare che ciò implica che spesso dalla funzione dirname() si ottiene uno slash od un punto nei casi in cui la vecchia versione avrebbe restituito una stringa vuota.

dirname() ha modificato il suo comportamento dal PHP 4.3.0. Controllare l'esempio:

<?php
 
//prima del PHP 4.3.0
dirname('c:/'); // restituisce '.'
 
//dopo il PHP 4.3.0
dirname('c:/'); // restituisce 'c:'
 
?>

dirname() è sicura con i dati binari dal PHP 5.0.0

Vedere anche: basename(), pathinfo() e realpath().

disk_free_space

(PHP 4 >= 4.1.0, PHP 5)

disk_free_space -- Restituisce lo spazio disponibile nella directory

Descrizione

float disk_free_space ( string directory )

Data una stringa contenente una directory, questa funzione restituirà il numero di byte disponibili nel corrispondente filesystem o nella partizione corrispondente.

Esempio 1. Esempio disk_free_space()
<?php // $df contiene il numero di byte disponibili in "/" $df = disk_free_space("/"); // Con Windows: disk_free_space("C:"); disk_free_space("D:"); ?>

Nota: Questa funzione non è eseguibile con file remoti, ma con file accessibili attraverso il filesystem del server.

Vedere anche disk_total_space()

disk_total_space

(PHP 4 >= 4.1.0, PHP 5)

disk_total_space -- Restituisce lo spazio totale di una directory

Descrizione

float disk_total_space ( string directory )

Data una stringa contenente una directory, questa funzione restituirà il numero totale di byte del filesystem o della partizione corrispondente.

Esempio 1. disk_total_space() example
// $df contiene il numero totale di byte disponibile su "/" $df = disk_total_space("/"); // Su Windows: disk_total_space("C:"); disk_total_space("D:"); ?>

Nota: Questa funzione non è eseguibile con file remoti, ma con file accessibili attraverso il filesystem del server.

Vedere anche disk_free_space()

diskfreespace

Questa funzione forza la scrittura di tutto l'output bufferizzato sulla risorsa puntata dal puntatore handle. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Il puntatore al file deve essere valido e deve puntare ad un file correttamente aperto da fopen(), popen() o fsockopen().

The file pointer must be valid, and must point to a file successfully opened by fopen() or fsockopen().

fgetc

(PHP 3, PHP 4, PHP 5)

fgetc -- Prende un carattere da un puntatore a file

Descrizione

string fgetc ( resource handle )

Restituisce una stringa contenente un singolo carattere letto dal file puntato da handle. Restituisce FALSE alla fine del file (EOF).

The file pointer must be valid, and must point to a file successfully opened by fopen() or fsockopen().

Avvertimento

Esempio 1. Un esempio per fgetc()
<?php $fp = fopen('somefile.txt', 'r'); if (!$fp) { echo 'Non si riesce ad aprire il file somefile.txt'; } while (false !== ($char = fgetc($fp))) { echo "$char\n"; } ?>

Nota: Questa funzione è binary-safe (gestisce correttamente i file binari)

Vedere anche fread(), fopen(), popen(), fsockopen() e fgets().

fgetcsv

(PHP 3 >= 3.0.8, PHP 4, PHP 5)

fgetcsv -- Prende una riga da un puntatore a file e l'analizza in cerca di campi CSV

Descrizione

array fgetcsv ( resource handle [, int lunghezza [, string delimitatore [, string enclosure]]] )

handle: Un puntatore valido a un file che punta a un file aperto con successo da fopen(), popen(), o fsockopen().
length (Opzionale): Deve essere più grande della linea più lunga (in caratteri) per essere trovato nel file CSV (permettendo di trascinare il carattere di fine linea). E' diventato opzionale in PHP 5.
delimiter (Opzionale): Setta il delimitatore di campo (un solo carattere). Virgola per default.
enclosure (Opzionale): Setta il carattere di inclusione nel campo (un solo carattere). Doppie virgolette per default. Aggiunto in PHP 4.3.0.

Simile a fgets() eccetto per il fatto che fgetcsv() analizza le righe lette alla ricerca di campi in formato CSV e restituisce un vettore contenente i campi letti.

Nota: Il parametro enclosure è stato aggiunto in PHP 4.3.0.

Handle deve essere un puntatore valido ad un file correttamente aperto da fopen(), popen() o fsockopen().

Lunghezza deve essere maggiore della linea più lunga trovata nel file CSV (compresi i caratteri di fine riga).

fgetcsv() restituisce FALSE in caso d'errore e al raggiungimento della fine del file.

Nota: Una riga vuota in un file CVS verrà riportata come un vettore contenente un solo campo vuoto (null) e non verrà trattata come un errore.

Esempio 1. Legge e scrive l'intero contenuto di un file CSV.
<?php $row = 1; $handle = fopen("test.csv","r"); while (($data = fgetcsv($handle, 1000, ",")) !== FALSE) { $num = count($data); echo "<p> $num campi sulla linea $row: <br /></p>\n"; $row++; for ($c=0; $c < $num; $c++) { echo $data[$c] . "<br>\n"; } } fclose($handle); ?>

fgetcsv() è diventata binary safe dal PHP 4.3.5

Nota: Se il PHP ha dei problemi a riconoscere la fine riga nella lettura di file su o creati da computer Macintosh, si può abilitare il parametro di configurazione auto_detect_line_endings.

Vedere anche explode(), file(), pack() e fputcsv().

fgets

(PHP 3, PHP 4, PHP 5)

fgets -- Prende una riga da un puntatore a file

Descrizione

string fgets ( resource handle, int length )

Restituisce una stringa di length - 1 byte letti dal file puntato da handle. La lettura termina quando sono stati letti length - 1 byte, oppure si incontra il carattere di newline (che viene incluso nel valore restituito), oppure alla fine del file (EOF) qualora giunga prima. Se non si specifica length, si assume come default 1k, o 1024 byte.

Se si verifica un errore, la funzione restituisce FALSE.

Errori comuni:

Le persone abituate alla semantica 'C' di fgets notino la differenza nel trattamento dell'EOF.

The file pointer must be valid, and must point to a file successfully opened by fopen() or fsockopen().

Segue un semplice esempio:
Esempio 1. Legge un file riga per riga
<?php $handle = fopen("/tmp/inputfile.txt", "r"); while (!feof($handle)) { $buffer = fgets($fd, 4096); echo $buffer; } fclose($handle); ?>

Nota: Il parametro length è diventato opzionale a partire da PHP 4.2.0, se omesso, si assume come lunghezza della linea 1024. A partire dalla versione 4.3, l'omissione del parametro length comporta la lettura del flusso d'ingresso sino al raggiungimento della fine della linea. Se la maggior parte delle righe lette dal file hanno dimensione superiore a 8KB, è più efficiente specificare la lunghezza massima della linea.

Nota: A partire da PHP 4.3 questa funzione è 'binary safe'. Le versioni precedenti non lo sono.

Nota: Se il PHP ha dei problemi a riconoscere la fine riga nella lettura di file su o creati da computer Macintosh, si può abilitare il parametro di configurazione auto_detect_line_endings.

Vedere anche fread(), fgetc(), stream_get_line(), fopen(), popen(), fsockopen() e stream_set_timeout().

fgetss

(PHP 3, PHP 4, PHP 5)

fgetss -- Prende una riga da un puntatore a file ed elimina i tag HTML

Descrizione

string fgetss ( resource handle [, int length [, string allowable_tags]] )

Identica a fgets(), eccetto per il fatto che fgetss tenta di eliminare tutti i tag HTML e PHP dal testo che legge.

Puoi utilizzare il terzo parametro (opzionale) per specificare quali tag non devono essere eliminati.

Nota: Il parametro allowable_tags è stato aggiunto in PHP 3.0.13, PHP 4.0.0.

Il parametro length è facoltativo dal PHP 5.

Nota: Se il PHP ha dei problemi a riconoscere la fine riga nella lettura di file su o creati da computer Macintosh, si può abilitare il parametro di configurazione auto_detect_line_endings.

Vedere anche fgets(), fopen(), fsockopen(), popen() e strip_tags().

file_exists

(PHP 3, PHP 4, PHP 5)

file_exists -- Controlla se un file o directory esiste

Descrizione

bool file_exists ( string filename )

Restituisce TRUE se il file o la directory specificata da filename esiste; FALSE altrimenti.

Sui sistemi Windows utlizzare //computername/share/filename oppure \\computername\share\filename per verificare file su dischi condivisi.

Esempio 1. Verificare l'esistenza di un file
<?php $filename = '/path/to/foo.txt'; if (file_exists($filename)) { echo "il file $filename esiste"; } else { echo "Il file $filename non esiste"; } ?>

Nota: I risultati di questa funzione saranno memorizzati. Vedere clearstatcache() per maggiori dettagli.

Suggerimento: A partire da PHP 5.0.0, questa funzione può essere utilizzata con alcuni URL wrappers. Fare riferimento a Appendice M per la lista di quali wrappers supportano le funzioni della famiglia stat().

Vedere anche is_readable(), is_writable(), is_file() e file().

file_get_contents

(PHP 4 >= 4.3.0, PHP 5)

file_get_contents -- Legge un file all'interno di una stringa

Description

string file_get_contents ( string filename [, bool use_include_path [, resource context [, int offset]]] )

Simile alla funzione file(), tranne che file_get_contents() restituisce il file in una stringa, iniziando allo specificato offset. Se si verifica un errore file_get_contents() restituirà FALSE

Nota: Il parametrooffset è stato aggiunto nel PHP 5.1.0.

Nota: Se si sta aprendo un URI con caratteri speciali, spazi ad esempio, si ha bisogno di decodificare l' URI con urlencode().

Nota: Questa funzione è binary-safe (gestisce correttamente i file binari)

Suggerimento: È possibile utilizzare una URL come un nome di file con questa funzione se fopen wrappers è stata abilitata. Per maggiori informazioni su come specificare i nomi di file vedere fopen() e Appendice M per avere la lista dei protocolli URL supportati.

Nota: Il supporto per il contesto è stato aggiunto in PHP 5.0.0. Per la descrizione del contesto, fare riferimento a Riferimento CXLIV, Stream Functions.

Avvertimento

When using SSL, Microsoft IIS will violate the protocol by closing the connection without sending a close_notify indicator. PHP will report this as "SSL: Fatal Protocol Error" when you reach the end of the data. To workaround this, you should lower your error_reporting level not to include warnings. PHP 4.3.7 and higher can detect buggy IIS server software when you open the stream using the https:// wrapper and will suppress the warning for you. If you are using fsockopen() to create an ssl:// socket, you are responsible for detecting and suppressing the warning yourself.

Vedere anche fgets(), file(), fread(), include(), readfile() e file_put_contents().

file_put_contents

(PHP 5)

file_put_contents -- Write a string to a file

Descrizione

int file_put_contents ( string filename, mixed data [, int flags [, resource context]] )

Identical to calling fopen(), fwrite(), and fclose() successively.

You can also specify the data parameter as an array (not multi-dimension arrays). This is equivalent to file_put_contents($filename, join('', $array)).

As of PHP 5.1.0, you may also pass a stream resource to the data parameter. In result, the remaining buffer of that stream will be copied to the specified file. This is similar with using stream_copy_to_stream().

Elenco dei parametri

filename: The file name where to write the data
data: The data to write. Can be either a string, an array or a stream resource (explained above).
flags: flags can take FILE_USE_INCLUDE_PATH, FILE_APPEND and/or LOCK_EX (acquire an exclusive lock), however the FILE_USE_INCLUDE_PATH option should be used with caution.
context: A context resource

Valori restituiti

The function returns the amount of bytes that were written to the file.

Log delle modifiche

Versione	Descrizione
5.1.0	Added support for `LOCK_EX` and the ability to pass a stream resource to the `data` parameter

Note

Nota: Questa funzione è binary-safe (gestisce correttamente i file binari)

Nota: Il supporto per il contesto è stato aggiunto in PHP 5.0.0. Per la descrizione del contesto, fare riferimento a Riferimento CXLIV, Stream Functions.

Suggerimento: È possibile utilizzare una URL come un nome di file con questa funzione se fopen wrappers è stata abilitata. Per maggiori informazioni su come specificare i nomi di file vedere fopen() e Appendice M per avere la lista dei protocolli URL supportati.

Vedere anche:

fopen()

fwrite()

file_get_contents()

file

(PHP 3, PHP 4, PHP 5)

file -- Legge l'intero file in un vettore

Descrizione

array file ( string filename [, int use_include_path [, resource context]] )

Identica a readfile(), eccetto per il fatto che file() restituisce il file in un vettore. Ogni elemento del vettore corrisponde ad una riga del file, con il carattere di newline ancora inserito. Se la funzione non riesce restituisce FALSE.

Puoi impostare il secondo parametro, use_include_path, (opzionale) ad "1", se vuoi cercare il file nel include_path.

<?php
// inserisce una pagina web in un array e la stampa. In questo esempio useremo il protocollo
// HTTP per ottenere il sorgente di un URL
$lines = file('http://www.example.com/');
// Ciclo attraverso l'array, si visualizzerà il sorgente come html ed i numeri di linea
foreach($lines as $line_num => $line) {
    echo "Line #<b>{$line_num}</b> : " . htmlspecialchars($line) . "<br />\n";
}

// Un'altro esempio, inserisce la pagina web in una stringa. Vedere anche  file_get_contents().
$html = implode('', file ('http://www.example.com/'));
?>

Suggerimento: È possibile utilizzare una URL come un nome di file con questa funzione se fopen wrappers è stata abilitata. Per maggiori informazioni su come specificare i nomi di file vedere fopen() e Appendice M per avere la lista dei protocolli URL supportati.

Nota: Ciascuna riga dell'array restituito conterrà il carattere di fine riga, occorre, pertanto, utilizzare rtrim() se si desidera rimuovere il carattere di fine riga.

Nota: Se il PHP ha dei problemi a riconoscere la fine riga nella lettura di file su o creati da computer Macintosh, si può abilitare il parametro di configurazione auto_detect_line_endings.

Nota: A partire da PHP 4.3.0 si può utilizzare file_get_contents() per memorizzare il contenuto di un file in una stringa in formato binario.

Nota: Il supporto per il contesto è stato aggiunto in PHP 5.0.0. Per la descrizione del contesto, fare riferimento a Riferimento CXLIV, Stream Functions.

Avvertimento

Vedere anche readfile(), fopen(), fsockopen(), popen(), file_get_contents() e include().

fileatime

(PHP 3, PHP 4, PHP 5)

fileatime -- Prende l'ora dell'ultimo accesso al file

Descrizione

int fileatime ( string filename )

Restituisce l'ora in cui il file ha ricevuto l'ultimo accesso, o FALSE in caso di errore. L'ora viene restituita come un timestamp Unix.

N.B.: Si suppone che l'atime di un file cambi ogni volta che i blocchi di dati del file vengono letti. Ciò può risultare costoso per le performance quando una applicazione accede con regolarità ad un numero elevato di file o directory. Alcuni filesystem Unix possono essere montati con l'aggiornamento dell'atime disabilitato per aumentare le performance di tali applicazioni; Gli spool delle news USENET costituiscono un esempio frequente. In tali filesystem queste funzioni sono inutili.

Nota: I risultati di questa funzione saranno memorizzati. Vedere clearstatcache() per maggiori dettagli.

Suggerimento: A partire da PHP 5.0.0, questa funzione può essere utilizzata con alcuni URL wrappers. Fare riferimento a Appendice M per la lista di quali wrappers supportano le funzioni della famiglia stat().

Esempio 1. Esempio per fileatime()
<?php // visualizza, ad esempio, che somefile.txt è stato aperto il: December 29 2002 22:16:23. $filename = 'somefile.txt'; if (file_exists($filename)) { echo "$filename è stato aperto il: " . date("F d Y H:i:s.", fileatime($filename)); } ?>

Vedere anche filemtime(), fileinode() e date().

filectime

(PHP 3, PHP 4, PHP 5)

filectime -- Prende l'ora in cui l'inode del file è stato modificato

Descrizione

int filectime ( string filename )

Restituisce l'ora in cui il file è stato cambiato l'ultima volta o FALSE in caso d'errore. L'ora viene restituita come un timestamp di Unix.

Nota: In molti filesystem Unix, si considera un file modificato, quando il suo inode viene cambiato; cioè quando i permessi, il proprietario, il gruppo o altri metadata dell'inode vengono aggiornati. Vedere anche filemtime() (che è ciò che ti serve se vuoi inserire la scritta "Ultima modifica: " nel piede delle tue pagine web) e fileatime().

Sappi anche che in alcuni testi su Unix si fa riferimento al ctime di un file come l'ora di creazione dello stesso. E' sbagliato. Nella maggioranza dei filesystem Unix non esiste un oa di creazione.

Nota: I risultati di questa funzione saranno memorizzati. Vedere clearstatcache() per maggiori dettagli.

Suggerimento: A partire da PHP 5.0.0, questa funzione può essere utilizzata con alcuni URL wrappers. Fare riferimento a Appendice M per la lista di quali wrappers supportano le funzioni della famiglia stat().

Esempio 1. Esempio di uso di fileatime()
<?php // Visualizza ad esempio: somefile.txt è stato modificato: December 29 2002 22:16:23. $filename = 'somefile.txt'; if (file_exists($filename)) { echo "$filename è stato modificato: " . date("F d Y H:i:s.", filectime($filename)); } ?>

Vedere anche filemtime().

filegroup

(PHP 3, PHP 4, PHP 5)

filegroup -- Restituisce il gruppo di un file

Descrizione

int filegroup ( string filename )

Restituisce il l'ID del gruppo del file, o FALSE in caso d'errore. L'ID del gruppo viene restituito in formato numerico: usa posix_getgrgid() per trasformarlo nel nome del gruppo. In caso di errore la funzione restituisce FALSE accompagnato da un errore di di livello E_WARNING.

Nota: I risultati di questa funzione saranno memorizzati. Vedere clearstatcache() per maggiori dettagli.

Suggerimento: A partire da PHP 5.0.0, questa funzione può essere utilizzata con alcuni URL wrappers. Fare riferimento a Appendice M per la lista di quali wrappers supportano le funzioni della famiglia stat().

Vedere anche: fileowner() e safe_mode_gid.

fileinode

(PHP 3, PHP 4, PHP 5)

fileinode -- Restituisce il numero di inode del file

Descrizione

int fileinode ( string filename )

Restituisce il numero di inode del file, o FALSE in caso d'errore.

Nota: I risultati di questa funzione saranno memorizzati. Vedere clearstatcache() per maggiori dettagli.

Suggerimento: A partire da PHP 5.0.0, questa funzione può essere utilizzata con alcuni URL wrappers. Fare riferimento a Appendice M per la lista di quali wrappers supportano le funzioni della famiglia stat().

Vedere anche stat().

filemtime

(PHP 3, PHP 4, PHP 5)

filemtime -- Restituisce l'ora delle modifiche al file

Descrizione

int filemtime ( string filename )

Restituisce l'ora dell'ultima modifica al file o FALSE in caso d'errore. L'ora viene restituita come un timestamp di Unix.

Nota: I risultati di questa funzione saranno memorizzati. Vedere clearstatcache() per maggiori dettagli.

Suggerimento: A partire da PHP 5.0.0, questa funzione può essere utilizzata con alcuni URL wrappers. Fare riferimento a Appendice M per la lista di quali wrappers supportano le funzioni della famiglia stat().

Nota: Questa funzione restituisce l'ora in cui i blocchi di dati di un file vengono scritti, cioè l'ora in cui il contenuto del file è cambiato.

Esempio 1. Esempio di uso di filemtime()
<?php // ad esempio visualizzerà: somefile.txt was last modified: December 29 2002 22:16:23. $filename = 'somefile.txt'; if (file_exists($filename)) { echo "$filename was last modified: " . date ("F d Y H:i:s.", filemtime($filename)); } ?>

Vedere anche filectime(), stat(), touch() e getlastmod().

fileowner

(PHP 3, PHP 4, PHP 5)

fileowner -- Restituisce il proprietario del file

Descrizione

int fileowner ( string filename )

Restituisce l'ID dell'utente proprietario del file, o FALSE in caso di errore. L'ID dell'utente viene restituito in formato numerico, usa posix_getpwuid() per trasformarlo nel nome dell'utente stesso.

Nota: I risultati di questa funzione saranno memorizzati. Vedere clearstatcache() per maggiori dettagli.

Suggerimento: A partire da PHP 5.0.0, questa funzione può essere utilizzata con alcuni URL wrappers. Fare riferimento a Appendice M per la lista di quali wrappers supportano le funzioni della famiglia stat().

Vedere anche stat()

fileperms

(PHP 3, PHP 4, PHP 5)

fileperms -- Restituisce i permessi sui file

Descrizione

int fileperms ( string filename )

Restituisce i permessi sui file, or FALSE in caso di errore.

Nota: I risultati di questa funzione saranno memorizzati. Vedere clearstatcache() per maggiori dettagli.

Suggerimento: A partire da PHP 5.0.0, questa funzione può essere utilizzata con alcuni URL wrappers. Fare riferimento a Appendice M per la lista di quali wrappers supportano le funzioni della famiglia stat().

Esempio 1. Mostra i permessi in valore ottale

<?php
echo substr(sprintf('%o', fileperms('/tmp')), -4);
echo substr(sprintf('%o', fileperms('/etc/passwd')), -4);
?>

Ciò produrrà il seguente output:

1777
0644

Esempio 2. Mostra gli interi permessi

<?php
$perms = fileperms('/etc/passwd');

if (($perms & 0xC000) == 0xC000) {
    // Socket
    $info = 's';
} elseif (($perms & 0xA000) == 0xA000) {
    // Symbolic Link
    $info = 'l';
} elseif (($perms & 0x8000) == 0x8000) {
    // Regular
    $info = '-';
} elseif (($perms & 0x6000) == 0x6000) {
    // Block special
    $info = 'b';
} elseif (($perms & 0x4000) == 0x4000) {
    // Directory
    $info = 'd';
} elseif (($perms & 0x2000) == 0x2000) {
    // Character special
    $info = 'c';
} elseif (($perms & 0x1000) == 0x1000) {
    // FIFO pipe
    $info = 'p';
} else {
    // Unknown
    $info = 'u';
}

// Owner
$info .= (($perms & 0x0100) ? 'r' : '-');
$info .= (($perms & 0x0080) ? 'w' : '-');
$info .= (($perms & 0x0040) ?
            (($perms & 0x0800) ? 's' : 'x' ) :
            (($perms & 0x0800) ? 'S' : '-'));

// Group
$info .= (($perms & 0x0020) ? 'r' : '-');
$info .= (($perms & 0x0010) ? 'w' : '-');
$info .= (($perms & 0x0008) ?
            (($perms & 0x0400) ? 's' : 'x' ) :
            (($perms & 0x0400) ? 'S' : '-'));

// World
$info .= (($perms & 0x0004) ? 'r' : '-');
$info .= (($perms & 0x0002) ? 'w' : '-');
$info .= (($perms & 0x0001) ?
            (($perms & 0x0200) ? 't' : 'x' ) :
            (($perms & 0x0200) ? 'T' : '-'));

echo $info;
?>

Ciò produrrà il seguente output:

-r--r--r--

Vedi anche is_readable(), e stat()

filesize

(PHP 3, PHP 4, PHP 5)

filesize -- Restituisce la dimensione del file

Descrizione

int filesize ( string filename )

Restituisce la dimensione di un file, o FALSE in caso d'errore.

Nota: Poichè il PHP tratta i tipi interi con il segno e diverse piattaforme utilizzano interi a 32 bit, filesize() può restituire valori non attendibili con file di dimensioni maggiori di 2GB. Per file con dimensione tra 2GB e 4GB si può tentare di ovviare utilizzando sprintf("%u", filesize($file)).

Nota: I risultati di questa funzione saranno memorizzati. Vedere clearstatcache() per maggiori dettagli.

Suggerimento: A partire da PHP 5.0.0, questa funzione può essere utilizzata con alcuni URL wrappers. Fare riferimento a Appendice M per la lista di quali wrappers supportano le funzioni della famiglia stat().

Esempio 1. Esempio di uso di filesize()
<?php // Ad esempio visualizzerà: somefile.txt: 1024 bytes $filename = 'somefile.txt'; echo $filename . ': ' . filesize($filename) . ' bytes'; ?>

Vedere anche file_exists()

filetype

(PHP 3, PHP 4, PHP 5)

filetype -- Restituisce il tipo di file

Descrizione

string filetype ( string filename )

Restituisce il tipo del file. Sono valori possibili fifo, char, dir, block, link, file e unknown.

Restituisce FALSE se si verifica un errore. Inoltre la funzione filetype() genera un errore di livello E_NOTICE se fallisce la chiamata a stat o se il tipo è sconosciuto.

Nota: I risultati di questa funzione saranno memorizzati. Vedere clearstatcache() per maggiori dettagli.

Suggerimento: A partire da PHP 5.0.0, questa funzione può essere utilizzata con alcuni URL wrappers. Fare riferimento a Appendice M per la lista di quali wrappers supportano le funzioni della famiglia stat().

Esempio 1. Esempio di uso di filetype()
<?php echo filetype('/etc/passwd'); // file echo filetype('/etc/'); // dir ?>

Vedere anche: is_dir(), is_file(), is_link(), file_exists(), stat() e mime_content_type().

flock

(PHP 3 >= 3.0.7, PHP 4, PHP 5)

flock -- Sistema di bloccaggio file

Descrizione

bool flock ( resource handle, int operation [, int &wouldblock] )

Il PHP supporta un tecnologia portabile per bloccare file completi in modalità advisory (tutti i programmi che vi accedono, devono usare lo stesso tipo di bloccaggio o non funzionerà).

Nota: flock()è obbligatorio sotto Windows.

flock() opera su handle che deve essere un puntatore ad un file aperto. operation può assumere uno dei valori seguenti:

Per acquisire una chiave condivisa (in lettura), imposta operation a LOCK_SH (usa 1 prima di PHP 4.0.1).
Per acquisire una chiave esclusiva (in scrittura), imposta operation a LOCK_EX (usa 2 prima di PHP 4.0.1).
Per rilasciare una chiave (condivisa o esclusiva), imposta operation a LOCK_UN (usa 3 prima PHP 4.0.1).
Se non vuoi che flock() blocchi mentre, imposta come LOCK_NB (4 prima di PHP 4.0.1) operation.

flock() ti permette di utilizzare un semplice modello di lettura/scrittura che in teoria può essere usato su qualsiasi piattaforma (inclusi molti sistemi Unix e anche Windows). Il terzo argomento (opzionale) può essere impostato a TRUE se la chiave puo bloccare (EWOULDBLOCK errno condition). Il blocco è realizzato anche da fclose() (che è anche richiamata automaticamente quando lo script termina).

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempio 1. Esempio di uso di flock()
<?php $fp = fopen("/tmp/lock.txt", "w+"); if (flock($fp, LOCK_EX)) { // Esegue un lock esclusivo fwrite($fp, "Write something here\n"); flock($fp, LOCK_UN); // rilascia il lock } else { echo "Non si riesce ad eseguire il lock del file !"; } fclose($fp); ?>

Nota: Poiché flock() richiede il puntatore ad un file, può occorre utilizzare un speciale file di lock per proteggere l'accesso a eventuali file che si desidera azzerare attraverso l'apertura in modalità di scrittura (usando "w" o "w+" come argomento di fopen()).

Avvertimento

La funzione flock() non funzione con NFS e con diversi altri file system di rete. Verificare sulla documentazione del proprio sistema operativo.

Su molti sistemi operativi flock() è implementato a livello di processo. Usando un server API multithread quale ISAPI non potrai basarti su flock() per proteggere i file da altri script PHP che girino in thread paralleli della stessa istanza del server!

La funzione flock() non è supportata su file system antiquati tipo FAT e i suoi derivati e pertanto in tali ambienti restituirà sempre FALSE (questo è vero soprattutto per gli utenti di Windows 98).

fnmatch

(PHP 4 >= 4.3.0, PHP 5)

fnmatch -- Match filename against a pattern

Description

bool fnmatch ( string pattern, string string [, int flags] )

fnmatch() checks if the passed string would match the given shell wildcard pattern.

This 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 ereg() or preg_match() for frontend search expression input may be way more convenient for non-programming users.

Esempio 1. Checking a color name against a shell wildcard pattern.

<?php
if (fnmatch("*gr[ae]y", $color)) {
  echo "some form of gray ...";
}
?>

Avvertimento

For now this function is not available on Windows or other non-POSIX compliant systems.

See also glob(), ereg(), preg_match() and the Unix manpage on fnmatch(3) for flag names (as long as they are not documented here ).

fopen

(PHP 3, PHP 4, PHP 5)

fopen -- Apre un file o un URL

Descrizione

resource fopen ( string filename, string mode [, bool use_include_path [, resource zcontext]] )

La funzione fopen() apre un collegamneto tra una risorsa, indicata dal parametro filename, ed un flusso. Se il parametro filename è del tipo "scheme://...", si assume essere un URL ed il PHP cercherà il modulo di gestione del protocollo (detto anche wrapper) per quello schema. Se non vi sono wrapper registrati per il protocollo richiesto, il PHP genererà un messaggio per aiutare a trovare potenziali problemi nello script e quindi procede considerando filename come un file regolare.

Se il PHP ha stabilito che filename indica un file locale, tenterà di aprire detto file come stream. Il file in oggetto dovrà esere accessibile dal PHP, occorre, pertanto, assicurasi che i permessi di accesso del file lo consentano. Se si è attivato il modalità sicura, oppure open_basedir si avranno ulteriori restrizioni.

Se il PHP ha stabilito che filename indica un protocollo registrato, e che tale protocollo è registrato come un URL di rete, il PHP verificherà che allow_url_fopen sia abilitato.Se fosse disabilitato, il PHP genererà un 'notice' e la funzione fallirà.

Nota: L'elenco dei protocolli supportati si trova in Appendice M. Alcuni protocolli (indicati anche come wrappers) supportano il context e/o le opzioni del php.ini Fare riferimento alle pagine specifiche del protocollo per avere l'elenco delle opzioni che possono essere utilizzate. (Ad esempio il parametro del php.ini user_agent è utilizzato dal wrapper http) Per una descrizione del contexts e del zcontext, fare riferimento a Riferimento CXLIV, Stream Functions.

Nota: Il supporto per il contesto è stato aggiunto in PHP 5.0.0. Per la descrizione del contesto, fare riferimento a Riferimento CXLIV, Stream Functions.

Nota: Come per PHP 4.3.2, la modalità di default è impostata a binarioper tutte le piattaforme che distinguono tra modalità binaria e testuale. Se si hanno problemi con i propri script dopo l'aggiornamento, provare a utilizzare il flag 't' come sostitutivo finchè si ha completato uno script maggiormente portabile come richiesto sopra.

Il parametro mode indica il tipo di accesso richiesto per il flusso. Esso può essere:

Tabella 1. Elenco dei possibili valori usati da fopen() per il parametro mode

`mode`	Descrizione
`'r'`	Apre in sola lettura; posiziona il puntatore all'inizio del file.
`'r+'`	Apre in lettura e scrittura; posiziona il puntatore all'inizio del file.
`'w'`	Apre il file in sola scrittura; posiziona il puntatore all'inizio del file e tronca il file alla lunghezza zero. Se il file non esiste, tenta di crearlo.
`'w+'`	Apre in lettura e scrittura; posiziona il puntatore all'inizio del file e tronce il file alla lunghezza zero. Se il file non esiste, tenta di crearlo.
`'a'`	Apre in sola scrittura; posiziona il puntatore alla fine del file. Se il file non esiste, tenta di crearlo.
`'a+'`	Apre in lettura e scrittura; posiziona il puntatore alla fine del file. Se il file non esiste, tenta di crearlo.
`'x'`	Crea ed apre il file in sola scrittura; posiziona il puntatore all'inizio del file. Se il file esiste già la chiamata a fopen() fallirà restituendo `FALSE` e verrà generato un errore di lievllo `E_WARNING`. Se il file non esiste si tenterà di crearlo. Questo equivale a specificare i flag `O_EXCL\|O_CREAT` nella sottostante chiamata a `open(2)` . Questa opzione è supportata a partire dalla versione 4.3.2 di PHP, e funziona solo con i file locali.
`'x+'`	Crea ed apre il file in lettura e scrittura; posiziona il puntatore all'inizio del file. Se il file esiste già la chiamata a fopen() fallirà restituendo `FALSE` e verrà generato un errore di lievllo `E_WARNING`. Se il file non esiste si tenterà di crearlo. Questo equivale a specificare i flag `O_EXCL\|O_CREAT` nella sottostante chiamata a `open(2)` . Questa opzione è supportata a partire dalla versione 4.3.2 di PHP, e funziona solo con i file locali.

Nota: Differenti famiglie di file system hanno differenti tipi di terminatori di riga. Quando si scrive un file di testo e si desidera inserire una interruzione di linea, occorre utilizzare il terminatore appropriato per il sistema operativo utilizzato. I sistemi basati su Unix utilizzano \n come terminatore di riga, i sistemi basati su Windows utilizzano \r\n mentre i sistemi Macintosh utilizzano \r.
Se si utilizza un errato terminatore di riga quando si scrivono i file, si può verificare che altre applicazioni accedendo a questi file abbiano comportamenti bizzarri.
Windows ha un flag di traduzione della modalità testo ('t') che in modo trasparente converte \n in \r\n mentre si lavora sul file. Ovviamente si ha anche il flag 'b' per forzare una modalità binaria, nella quale non si ha la conversione dei dati. Se si usano questi flag, 'b' oppure 't', devono essere posizionati come ultimo carattere del parametro mode.
La modalità di conversione di default dipende dalla SAPI e dalla versione di PHP che si sta utlizzando, pertanto si incoraggia l'uso dei flag appropriati per aumentare la portabilità degli script. Si dovrebbe utilizzare 't' se si lavora con dei file di testo, e si utilizza \n per indicare il fine linea, e ci si aspetta che che altre applicazioni, tipo notepad, leggano il file prodotto. In tutti gli altri casi si dovrebbe utilizzare 'b'
Se non si specifica il flag 'b' quando si lavora con file binari, si possono avere situazioni anomale nei dati, tipo immagini corrotte, e situazioni anomale con i caratteri \r\n.

Nota: Per la portabilità, si consiglia vivamente di usare sempre il flag 'b' quando si aprono files con fopen().

Nota: Inoltre, sempre per la portabilità, è anche fortemente raccomandato di aggiornare il codice che utilizza o che si avvale del mode 't' così da utilizzare il corretto terminatore di linea invece del 'b' mode.

Il terzo parametro opzionale use_include_path può essere impostato a '1' oppure a TRUE se si desidera cercare il file in include_path.

Se la open fallisce, la funzione restituisce FALSE e viene generato un errore di tipo E_WARNING. Si può utilizzare @ per sopprimere questo warning.

Esempio 1. Esempi di fopen()
<?php $handle = fopen("/home/rasmus/file.txt", "r"); $handle = fopen("/home/rasmus/file.gif", "wb"); $handle = fopen("http://www.example.com/", "r"); $handle = fopen("ftp://user:password@example.com/somefile.txt", "w"); ?>

Se si dovessero manifestare dei problemi nella lettura o scrittura di file e si sta utilizzando la versione server di PHP, occorre verificare che i file e le directory utilizzate dallo script siano accessibili dal processo del server.

Sulla piattaforma Windows occorre prestare attenzione ai backslash nei percorsi dei file; questi devono essere preceduti dal caratteri di escape '\', oppure utilizzare lo slash '/'.

<?php
$handle = fopen("c:\\data\\info.txt", "r");
?>

Avvertimento

Nota: Quando safe-mode è abilitato, PHP controlla che la directory nella quale si sta lavorando, abbia lo stesso UID dello script che è in esecuzione.

Vedere anche Appendice M, fclose(), fgets(), fread(), fwrite(), fsockopen(), file(), file_exists(), is_readable(), stream_set_timeout() e popen().

fpassthru

(PHP 3, PHP 4, PHP 5)

fpassthru -- Invia tutti i dati rimanenti su un puntartore a file

Descrizione

int fpassthru ( resource handle )

Legge fino a EOF sul puntatore al file dato e scrive i risultati sul buffer di output.

Se si verifica un errore, fpassthru() restituisce FALSE. In caso positivo fpassthru() restituisce il numero di caratteri letti da handle scritti in output.

The file pointer must be valid, and must point to a file successfully opened by fopen() or fsockopen().

Può essere necessario chiamarerewind() per resettare il puntatore al file all'inizio del file stesso nel caso si abbbia già scritto dai dati nel file. Il file viene chiuso quando si sia chiamata fpassthru() leggendolo (lasciandohandle inutilizzato).

Se desideri semplicemente inviare il contenuto di un file sul buffer di output, senza doverlo modificare o posizionarti in un particolare offset, potresti preferire readfile(), che ti salva la chiamata a fopen().

Nota: Quando si utilizza fpassthru() con file binari su sistemi Windows si dovrebbe essere certi di aprire il file in modalità binaria aggiungendo b alla modalità utilizzata nella chiamata a fopen().
Si incoraggia l'uso del flag b quando si trattano file binari, anche se il sistema non lo richiede; in questo modo si rendono gli script più trasportabili.

Esempio 1. Utilizzo di fpassthru() con file binari
<?php // apre il file in modalità binaria $name = ".\public\dev\img\ok.png"; $fp = fopen($name, 'rb'); // invia i giusti header header("Content-Type: image/png"); header("Content-Length: " . filesize($name)); // invia l'immagine ed esce dallo script fpassthru($fp); exit; ?>

Vedere anche readfile(), fopen(), popen() e fsockopen()

fputcsv

(PHP 5 >= 5.1.0RC1)

fputcsv -- Format line as CSV and write to file pointer

Description

int fputcsv ( resource handle [, array fields [, string delimiter [, string enclosure]]] )

fputcsv() formats a line (passed as a fields array) as CSV and write it to the specified file handle. Returns the length of the written string, or FALSE on failure.

The optional delimiter parameter sets the field delimiter (one character only). Defaults as a comma: ,.

The optional enclosure parameter sets the field enclosure (one character only) and defaults to a double quotation mark: ".

Esempio 1. fputcsv() example
<?php $list = array ( 'aaa,bbb,ccc,dddd', '123,456,789', '"aaa","bbb"' ); $fp = fopen('file.csv', 'w'); foreach ($list as $line) { fputcsv($fp, split(',', $line)); } fclose($fp); ?>

Nota: Se il PHP ha dei problemi a riconoscere la fine riga nella lettura di file su o creati da computer Macintosh, si può abilitare il parametro di configurazione auto_detect_line_endings.

fputs

(PHP 3, PHP 4, PHP 5)

fputs -- Alias di fwrite()

Descrizione

fputs() è un alias di fwrite().

fread

(PHP 3, PHP 4, PHP 5)

fread -- Legge un file salvaguardando la corrispondenza binaria

Descrizione

string fread ( resource handle, int length )

fread() legge fino a length byte dal puntatore al file indicato da handle. La lettura finisce quando sono stati letti length byte o è stata raggiunta EOF, o (nel caso di flussi via rete) quando un pacchetto divnta disponibile, in base a quale evento accada prima.

<?php
// copia il contenuto di un file in una stringa
$filename = "/usr/local/something.txt";
$handle = fopen($filename, "r");
$contents = fread($handle, filesize($filename));
fclose($handle);
?>

Avvertimento

Sui sistemi che differenziano fra file di testo e binari (ad esempio Windows) il file deve essere aperto con il parametro mode di fopen() impostato a 'b'.

<?php
$filename = "c:\\files\\somepic.gif";
$handle = fopen($filename, "rb");
$contents = fread($handle, filesize($filename));
fclose($handle);
?>

Avvertimento

Quando si ricevono dati via rete o pipe, tipo quelli ottenuti leggendo da file remoti o da popen() e fsockopen(), la lettura si fermerà dopo avere ricevuto il pacchetto disponibile. Questo significa che i dati sono ricevuti a blocchi che devono essere raggruppati, come illustrato nell'esempio seguente.

<?php
$handle = fopen("http://www.example.com/", "rb");
$contents = '';
while (!feof($handle))  {
   $contents .=fread($handle, 8192);
  }
    $contents .= $data;
} while (true);
fclose($handle);
?>

Nota: Se si desidera ottenere il contenuto del file in una stringa, utilizzare la funzione file_get_contents() la quale è ancora più performante del codice precedente.

Vedere anche fwrite(), fopen(), fsockopen(), popen(), fgets(), fgetss(), fscanf(), file() e fpassthru().

fscanf

(PHP 4 >= 4.0.1, PHP 5)

fscanf -- Analizza l'input da un file secondo un determinato formato

Descrizione

mixed fscanf ( resource handle, string format [, mixed &...] )

La funzione fscanf() è simile a sscanf(), ma prende il proprio input da un file associato con handle e interpreta l'input in accordo con il parametro format, che viene descritto nella documentazione della funzione sprintf(). Se vengono passati solo due parametri a questa funzione, i valori esaminati verranno restituiti in un vettore. Altrimenti, se vengono passati i parametri opzionali, la funzione restituirà il numero dei valori assegnati. I parametri opzionali devono essere passati da reference.

Ogni spazio nella stringa di formato identifica uno spazio nel flusso di input. Questo significa che anche i tab \t presenti nella stringa di formato possono identiicare uno spazio nel flusso di input.

Esempio 1. Esempio di fscanf()
<?php $handle = fopen("users.txt", "r"); while ($userinfo = fscanf ($handle, "%s\t%s\t%s\n")) { list ($name, $profession, $countrycode) = $userinfo; //... fai quacosa coi valori ... } fclose($handle); ?>

Esempio 2. Cntyennts of users.txt
javier argonaut pe hiroshi sculptor jp robert slacker us luigi florist it

Nota: Nelle versioni di PHP precedenti alla 4.3.0, il numero massimo di caratteri letti da un file era di 512 (o fino al primo \n, dipende da quale si incontra prima). Dal PHP 4.3.0 si possono esaminare linee di lunghezza arbitraria.

Vedere anche fread(), fgets(), fgetss(), sscanf(), printf() e sprintf().

fseek

(PHP 3, PHP 4, PHP 5)

fseek -- Sposta un puntatore sul file

Descrizione

int fseek ( resource handle, int offset [, int whence] )

Imposta l'indicatore di posizione del file riferito da handle. La nuova posizione, misurata in byte dall'inizio del file, si ottiene aggiungendo offset alla posizione specificata da whence, i cui valori sono definiti come segue:

SEEK_SET - Imposta la posizione uguale a offset byte.

SEEK_CUR - Imposta la posizione alla attuale più offset.

SEEK_END - Imposta la posizione alla fine del file più offset. (To move to a position before the end-of-file, you need to pass a negative value in offset.)

Se whence non viene specificato, viene assunto come SEEK_SET.

In caso di successo, restituisce 0; altrimenti, restituisce -1. Nota che spostarsi oltre EOF non è considerato un errore.

Esempio 1. Esempio di uso di fseek()
<?php $fp = fopen('somefile.txt'); // Lettura di qualche dato $data = fgets($fp, 4096); // si torna ad inizio file // come rewind($fp); fseek($fp, 0); ?>

Non può essere usato su puntatori a file restituiti da fopen() se è in uso il formato "http://" o "ftp://". fseek() da anche risultati non definiti per stream in modalità append-only (aperti con il flag "a").

Nota: L'argomento whence è stato aggiunto dopo PHP 4.0.0.

Vedere anche ftell() e rewind().

fstat

(PHP 4, PHP 5)

fstat -- Restituisce le informazioni riguardanti un file attraverso un puntatore al file aperto

Descrizione

array fstat ( resource handle )

Restituisce le statistiche del file aperto dal puntatore handle. Questa funzione è simile a stat() eccetto per il fatto che opera su un puntatore a file aperto invece che su un nome di file.

Restituisce un vettore con le statistiche del file con il formato del vettore è descritto nella pagina di stat().

Esempio 1. Esempio di uso di fstat()
<?php // apertura del file $fp = fopen("/etc/passwd", "r"); // raccolta delle informazioni $fstat = fstat($fp); // chiusura del file fclose($fp); // scrittura della sola parte associativa print_r(array_slice($fstat, 13)); ?>
l'esempio visualizzerà :
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 )

Nota: I risultati di questa funzione saranno memorizzati. Vedere clearstatcache() per maggiori dettagli.

Nota: Questa funzione non è eseguibile con file remoti, ma con file accessibili attraverso il filesystem del server.

ftell

(PHP 3, PHP 4, PHP 5)

ftell -- Comunica la posizione di lettura/scrittura del puntatore al file

Descrizione

int ftell ( resource handle )

Restituisce la posizione del puntatore al file indicato da handle; cioè, il suo offset all'interno del flusso del file.

Se si verifica un errore, restituisce FALSE.

Il puntatore al file deve essere valido e deve puntare ad un file aperto correttamente da fopen() o da popen(). ftell() da risultati non definiti per stream in modalità append-only (aperti col flag "a").

Esempio 1. Esempio di uso di ftell()
<?php // apre un file e legge alcuni dati $fp = fopen("/etc/passwd", "r"); $data = fgets($fp, 12); // where are we ? echo ftell($fp); // 11 fclose($fp); ?>

Vedere anche fopen(), popen(), fseek() e rewind().

ftruncate

(PHP 4, PHP 5)

ftruncate -- Tronca un file alla lunghezza data

Descrizione

bool ftruncate ( resource handle, int size )

Prende il puntatore al file handle e tronca il file alla lunghezza indicata da size. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Nota: Nelle versioni di PHP precedenti alla 4.3.3, la funzione ftruncate() restituisce un integer di valore 1 se l'operazione riesce, anziché restituire boolean TRUE.

fwrite

(PHP 3, PHP 4, PHP 5)

fwrite -- Scrive un file salvaguardando la corrispondenza binaria

Descrizione

int fwrite ( resource handle, string string [, int length] )

fwrite() scrive il contenuto di string nel flusso del file puntato da handle. Se l'argomento length è specificato la scrittura si arresterà dopo aver scritto length byte o alla fine di string se si verificasse prima.

fwrite() returns the number of bytes written, or FALSE on error.

Nota che se il parametro length viene specificato, allora l'opzione di configurazione magic_quotes_runtime verrà ignorata e nessuno slash verrà skippato da string.

Nota: Su sistemi che differenzino fra file binari e di testo (come Windows) il file deve essere aperto includendo 'b' nel paramentro mode di fopen().

Esempio 1. Un semplice esempio di fwrite
<?php $filename = 'test.txt'; $somecontent = "Aggiunge questa riga al file\n"; // Verifica che il file esista e sia riscrivibile if (is_writable($filename)) { // In questo esempio apriamo $filename in append mode. // Il puntatore del file è posizionato in fondo al file // è qui che verrà posizionato $somecontent quando eseguiremo fwrite(). if (!$handle = fopen($filename, 'a')) { echo "Non si riesce ad aprire il file ($filename)"; exit; } // Scrive $somecontent nel file aperto. if (!fwrite($handle, $somecontent) ===FALSE) { echo "Non si riesce a scrivere nel file ($filename)"; exit; } echo "Riuscito, scritto ($somecontent) nel file ($filename)"; fclose($handle); } else { echo "Il file $filename non è accessibile"; } ?>

Vedere anche fread(), fopen(), fsockopen(), popen() e file_put_contents().

glob

(PHP 4 >= 4.3.0, PHP 5)

glob -- Find pathnames matching a pattern

Description

array glob ( string pattern [, int flags] )

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. No tilde expansion or parameter substitution is done.

Returns an array containing the matched files/directories or FALSE on error.

Valid flags:

GLOB_MARK - Adds a slash to each item 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
Nota: Before PHP 4.3.3 GLOB_ONLYDIR was not available on Windows and other systems not using the GNU C library.
GLOB_ERR - Stop on read errors (like unreadable directories), by default errors are ignored
Nota: GLOB_ERR was added in PHP 5.1

Esempio 1. Convenient way how glob() can replace opendir() and friends.
<?php foreach (glob("*.txt") as $filename) { echo "$filename size " . filesize($filename) . "\n"; } ?>
Output will look something like:
funclist.txt size 44686 funcsummary.txt size 267625 quickref.txt size 137820

Nota: Questa funzione non è eseguibile con file remoti, ma con file accessibili attraverso il filesystem del server.

is_dir

(PHP 3, PHP 4, PHP 5)

is_dir -- Dice se la stringa corrisponde ad una directory

Descrizione

bool is_dir ( string filename )

Restituisce TRUE se il nome file esiste ed è una directory. Se filename è un nome file relativo, verrà controllato relativamente alla directory di lavoro in uso.

Nota: I risultati di questa funzione saranno memorizzati. Vedere clearstatcache() per maggiori dettagli.

Esempio 1. Esempio di uso di is_dir()
<? var_dump(is_dir('a_file.txt')) . "\n"; var_dump(is_dir('bogus_dir/abc')) . "\n"; var_dump(is_dir('..')); //su di una dir ?>
L'esempio precedente visualizzerà:
bool(false) bool(false) bool(true)

Suggerimento: A partire da PHP 5.0.0, questa funzione può essere utilizzata con alcuni URL wrappers. Fare riferimento a Appendice M per la lista di quali wrappers supportano le funzioni della famiglia stat().

Vedere anche chdir(), dir, opendir(), is_file() e is_link().

is_executable

(PHP 3, PHP 4, PHP 5)

is_executable -- Dice se il file indicato è eseguibile

Descrizione

bool is_executable ( string filename )

Restituisce TRUE se il filename esiste ed è un eseguibile.

La funzione is_executable() sarà disponibile sui sistemi Windows a partire dalla versione 5.0.0 di PHP.

Esempio 1. Esempio di uso di is_executable()
<?php $file = '/home/vincent/somefile.sh'; if (is_executable($file)) { echo $file.' è eseguibile'; } else { echo $file.' non è eseguibile'; } ?>

Nota: I risultati di questa funzione saranno memorizzati. Vedere clearstatcache() per maggiori dettagli.

Suggerimento: A partire da PHP 5.0.0, questa funzione può essere utilizzata con alcuni URL wrappers. Fare riferimento a Appendice M per la lista di quali wrappers supportano le funzioni della famiglia stat().

Vedere anche is_file() e is_link().

is_file

(PHP 3, PHP 4, PHP 5)

is_file -- Dice se il file è un file regolare

Descrizione

bool is_file ( string filename )

Restituisce TRUE se il filename esiste ed è un file regolare.

Nota: I risultati di questa funzione saranno memorizzati. Vedere clearstatcache() per maggiori dettagli.

Suggerimento: A partire da PHP 5.0.0, questa funzione può essere utilizzata con alcuni URL wrappers. Fare riferimento a Appendice M per la lista di quali wrappers supportano le funzioni della famiglia stat().

Vedere anche is_dir() e is_link().

is_link

(PHP 3, PHP 4, PHP 5)

is_link -- Dice se il file è un link simbolico

Descrizione

bool is_link ( string filename )

Restituisce TRUE se il filename esiste ed è un link simbolico.

Nota: I risultati di questa funzione saranno memorizzati. Vedere clearstatcache() per maggiori dettagli.

Suggerimento: A partire da PHP 5.0.0, questa funzione può essere utilizzata con alcuni URL wrappers. Fare riferimento a Appendice M per la lista di quali wrappers supportano le funzioni della famiglia stat().

Vedere anche is_dir() e is_file().

is_readable

(PHP 3, PHP 4, PHP 5)

is_readable -- Dice se un file è leggibile

Descrizione

bool is_readable ( string filename )

Restituisce TRUE se filename esiste ed è leggibile.

Ricorda che PHP può accedere al file come l'utente che è rappresentato dal server (spesso 'nobody'). Non sono prese in conto limitazione di sicurezza.

Nota: I risultati di questa funzione saranno memorizzati. Vedere clearstatcache() per maggiori dettagli.

Suggerimento: A partire da PHP 5.0.0, questa funzione può essere utilizzata con alcuni URL wrappers. Fare riferimento a Appendice M per la lista di quali wrappers supportano le funzioni della famiglia stat().

Vedere anche is_writable(), file_exists() e fgets().

is_uploaded_file

(PHP 3 >= 3.0.17, PHP 4 >= 4.0.3, PHP 5)

is_uploaded_file -- Dice se un file fù caricato via HTTP POST.

Descrizione

bool is_uploaded_file ( string filename )

Restituisce TRUE se il file chiamato per filename è stato spedito in upload col metodo HTTP POST. Ciò è utile per rendere sicuro il fatto da un utente malizioso non abbia cercato di forzare uno script ad agire sul file sul quale non dovrebbe essere svolto alcun lavoro--ad esempio, /etc/passwd.

Questo controllo è particolarmente importante in caso esista una qualunque possibilità che una qualunque cosa che viaggia durante l'upload del file, possa rivelarne il contenuto all'utente, o anche ad altri utenti che operano sullo stesso sistema.

is_uploaded_file() è disponibile solo nella versione PHP 3, dopo la 3.0.16, e nella versione 4 dopo la 4.0.2. Se hai delle perplessità nell'usare una versione più recente, puoi utilizzare una delle seguenti funzioni per proteggere te stesso:

Nota: L'esempio seguente not lavorerà con le versioni PHP 4 dopo la 4.0.2. Ciò dipende da funzionalità interne a PHP che sono variate dopo tale versione.

Esempio 1. is_uploaded_file() example

<?php
/* Userland test for uploaded file. */
function is_uploaded_file($filename) 
{
    if (!$tmp_file = get_cfg_var('upload_tmp_dir')) {
        $tmp_file = dirname(tempnam('', ''));
    }
    $tmp_file .= '/' . basename($filename);
    /* User might have trailing slash in php.ini... */
    return (ereg_replace('/+', '/', $tmp_file) == $filename);
}

/* This is how to use it, since you also don't have
 * move_uploaded_file() in these older versions: */
if (is_uploaded_file($HTTP_POST_FILES['userfile'])) {
    copy($HTTP_POST_FILES['userfile'], "/place/to/put/uploaded/file");
} else {
    echo "Possibile attacco su file in uploading: filename '$HTTP_POST_FILES[userfile]'.";
}
?>

Vedi anche move_uploaded_file(), e la sezione Handling file uploads per un semplice esempio di utilizzo.

is_writable

(PHP 4, PHP 5)

is_writable -- Dice se un file è scrivibile

Descrizione

bool is_writable ( string filename )

Restituisce TRUE se filename esiste ed è scrivibile. L'argomento filename può essere un nome di directory che ti permetta di verificare se una directory è scrivibile.

Tieni presente che PHP può accedere al file con lo user id del web server (spesso 'nobody'). Non sono prese in considerazioni limitazioni di sicurezza.

Nota: I risultati di questa funzione saranno memorizzati. Vedere clearstatcache() per maggiori dettagli.

Suggerimento: A partire da PHP 5.0.0, questa funzione può essere utilizzata con alcuni URL wrappers. Fare riferimento a Appendice M per la lista di quali wrappers supportano le funzioni della famiglia stat().

Vedere anche is_readable(), file_exists() e fwrite().

is_writeable

(PHP 3, PHP 4, PHP 5)

is_writeable -- Alias di is_writable()

Descrizione

Questo è un alias per is_writable()

link

(PHP 3, PHP 4, PHP 5)

link -- Crea un hard link

Descrizione

bool link ( string target, string link )

link() crea un hard link. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Nota: Questa funzione non è eseguibile con file remoti, ma con file accessibili attraverso il filesystem del server.

Nota: Questa funzione non è implementata su piattaforme Windows

Vedere anche symlink() per creare soft link, e readlink() assieme a linkinfo().

linkinfo

(PHP 3, PHP 4, PHP 5)

linkinfo -- Restituisce informazioni su un collegamento

Descrizione

int linkinfo ( string path )

linkinfo() restituisce il st_dev campo della struttura stat dello Unix C restituita dalla chiamata di sistema lstat. Questa funzione è usata per verificare se un link (puntato da path) esiste davvero (usando lo stesso metodo della macro S_ISLNK definita in stat.h). Restituisce 0 o FALSE in caso di errore.

Esempio 1. Esempio di uso di linkinfo()
<?php echo linkinfo('/vmlinuz'); // 835 ?>

Nota: Questa funzione non è implementata su piattaforme Windows

Vedere anche symlink(), link() e readlink().

lstat

(PHP 3 >= 3.0.4, PHP 4, PHP 5)

lstat -- Da informazioni su un file o un link simbolico

Descrizione

array lstat ( string filename )

Raccoglie le statistiche del file o del link simbolico chiamato filename.. Questa funzione è identica alla funzione stat() eccetto che se il paramametro filename è un link simbolico valido, viene restituito lo stato del link simbolico, non lo stato del file puntato dal link simbolico.

Nota: I risultati di questa funzione saranno memorizzati. Vedere clearstatcache() per maggiori dettagli.

Suggerimento: A partire da PHP 5.0.0, questa funzione può essere utilizzata con alcuni URL wrappers. Fare riferimento a Appendice M per la lista di quali wrappers supportano le funzioni della famiglia stat().

Vedere anche stat().

mkdir

(PHP 3, PHP 4, PHP 5)

mkdir -- Crea una directory

Descrizione

int mkdir ( string pathname [, int mode [, bool recursive [, resource context]]] )

Tenta di creare la directory specificata da pathname.

Nota che probabilmente vuoi specificare mode come un ottale, per cui deve iniziare con uno zero. La modalità è anche modificata dall'umask corrente, che puoi cambiare con umask().

Nota: Il parametro mode è ignorato sui sistemi Windows, ed è opzionale dal PHP 4.2.0.

Il parametro mode viene impostato a 0777 per default; ciò significa dare i maggiori accessi possibili. Per maggiori dettagli sui valori di mode, leggere le pagine relative a chmod().
Esempio 1. Esempio di uso di mkdir()
<?php mkdir("/path/to/my/dir", 0700); ?>

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Nota: A partire da PHP 5.0.0 la funzione mkdir() può anche essere utilizzata con alcuni wrapper URL. Fare riferimento a Appendice M per avere l'elenco dei wrapper supportati da mkdir().

Nota: I parametri recursive e context sono stati aggiunti in PHP 5.0.0.

Nota: Quando safe-mode è abilitato, PHP controlla che la directory nella quale si sta lavorando, abbia lo stesso UID dello script che è in esecuzione.

Vedere anche rmdir().

move_uploaded_file

(PHP 4 >= 4.0.3, PHP 5)

move_uploaded_file -- Muove un file caricato in una nuova posizione

Descrizione

bool move_uploaded_file ( string filename, string destination )

Questa funzione verifica che il file indicato da filename è un file validamente caricato (nel senso che è stato caricato attraverso il meccanismo di caricamento HTTP POST di PHP). Se il file è valido, verrà spostato nel file dato da destination.

Se filename non è un file validamente caricato, allora non verrà compiuta alcuna azione e move_uploaded_file() restituirà FALSE.

Se filename è un file validamente caricato, ma non può essere mossi per qualche ragione, non verrà compiuto alcunchè e move_uploaded_file() restituirà FALSE. In più verrà visualizzato un avviso di pericolo.

Questo tipo di verifica è particolarmente importante se sussiste la possibilità che qualcosa fatto con i file caricati possa rivelare il loro contenuto agli utenti o ad altri utenti dello stesso sistema.

Nota: Quando safe-mode è abilitato, PHP controlla che i file o le directory sulle quali si sta andando a lavorare, abbiano lo stesso UID dello script che è in esecuzione.

Nota: move_uploaded_file() non è limitato dalle normali restrizioni del modalità sicura UID. QCiò non è insicuro poichè move_uploaded_file() operara solo sui file uplodati via PHP.

Avvertimento

Se il file di destinazione esiste, sarà sovrascritto.

Vedere anche is_uploaded_file() e la sessione Handling file uploads per un semplice esempio.

parse_ini_file

(PHP 4, PHP 5)

parse_ini_file -- Legge il file di configurazione

Descrizione

array parse_ini_file ( string filename [, bool process_sections] )

La funzione parse_ini_file() carica il file ini specificato da filename, e restituisce le impostazioni in un array associativo. Impostando process_sections a TRUE si ottiene una matrice multi-dimensionale con in nomi delle sezioni e le impostazioni ivi incluse. Per default process_sections è impostato a falso FALSE

Nota: Questa funzione non è collegata con il file php.ini. Questo è già elaborato al momento in cui gira lo script. Questa funzione può essere utilizzata per leggere i file ini propri dell'applicazione.

Nota: Se in un valore il file ini contiene caratteri non alfanumerici questi debbono essere delitimitati dai doppi apici (").

Nota: Dalla versione 4.2.1 di PHP questa funzione è limitata da by modalità sicura e da open_basedir.

Nota: Esistono parole riservate che non possono essere utilizzare come chiavi nei file ini. Queste includono: null, yes, no, true, and false.

La struttura del file ini è simile a quella del php.ini.

Le Costanti possono essere definite in un file ini, quindi se si definisce la costante come un valore da file ini prima di eseguire parse_ini_file(), la funzione integrerà nella costante il valore letto. Saranno considerati solo i valori ini. Ad esempio:

Esempio 1. Contenuto di sample.ini
; Questo è un esempio di file di configurazione ; I commenti cominciano con ';', come in php.ini [first_section] one = 1 five = 5 animal = BIRD [second_section] path = /usr/local/bin URL = "http://www.example.com/~username"

Esempio 2. Esempio di uso di parse_ini_file()
<?php define('BIRD', 'Dodo bird'); // Lettura senza sezioni $ini_array = parse_ini_file("sample.ini"); print_r($ini_array); // Lettura con sezioni $ini_array = parse_ini_file("sample.ini", true); print_r($ini_array); ?>
L'esempio produrrà:
Array ( [one] => 1 [five] => 5 [animal] => Dodo bird [path] => /usr/local/bin [URL] => http://www.example.com/~username ) Array ( [first_section] => Array ( [one] => 1 [five] => 5 [animal] = Dodo bird ) [second_section] => Array ( [path] => /usr/local/bin [URL] => http://www.example.com/~username ) )

La chiavi e le sezioni composte da numeri come considerate dal PHP come interi quindi i numeri che iniziano con 0 sono trattati come numeri ottali, e inumeri che iniziano con 0x sono considerati esadecimali.

pathinfo

(PHP 4 >= 4.0.3, PHP 5)

pathinfo -- Restituisce informazioni su un percorso di file

Descrizione

array pathinfo ( string path [, int options] )

pathinfo() restituisce un vettore associativo contenente informazioni riguardo path. Nel vettore vegono riportati i seguenti elementi: dirname, basename e extension.

Si può specificare quali elementi vengano restituiti con parametri opzionali options. E' composto da PATHINFO_DIRNAME, PATHINFO_BASENAME e PATHINFO_EXTENSION. Assume per defalut la restituzione di tutti gli elementi.

Esempio 1. pathinfo() Example
<?php $path_parts = pathinfo('/www/htdocs/index.html'); echo $path_parts['dirname'], "\n"; echo $path_parts['basename'], "\n"; echo $path_parts['extension'], "\n"; ?>
Produrrà:
/www/htdocs index.html html

Nota: Per informazioni su come recuperare il path corrente, leggere la sezione su variabili riservate predefinite.

Vedere anche dirname(), basename(), parse_url() e realpath().

pclose

(PHP 3, PHP 4, PHP 5)

pclose -- Chiude un puntatore ad un file di processo

Descrizione

int pclose ( resource handle )

Chiude un puntatore ad una pipe aperto da popen().

Il puntatore deve essere valido e deve essere stato restituito da un chiamata a popen() terminata con successo.

Restituisce lo stato di terminazione del processo che stava girando.

Vedere anche popen().

popen

(PHP 3, PHP 4, PHP 5)

popen -- Apre un puntatore ad un file di processo

Descrizione

resource popen ( string command, string mode )

Apre una pipe ad un processo eseguito forzando il comando dato da command.

Restituisce un puntatore a file identico a quello restituito da fopen(), eccetto che per il fatto che è unidirezionale (può solo essere usato per la lettura o la scrittura) e deve essere chiudo con pclose(). Questo puntatore può essere usato con fgets(), fgetss() e fwrite().

Se si verifica un errore, restituisce FALSE.

Nota: Se si sta cercando un supporto bi-direzionale (2 vie), utilizzare proc_open().

Esempio 1. Esempio di uso di popen()
<?php $handle = popen("/bin/ls", "r"); ?>

Se il comando che deve essere eseguito non è trovato, la funzione restituisce una risorsa valida. Questo sembra strano, ma ha un senso; esso permette di accedere ai messaggi di erore restituiti dalla shell:

<?php
error_reporting(E_ALL);

/* Aggiunge una redirezione, così possiamo ottenere stderr. */
$handle = popen('/path/to/spooge 2>&1', 'r');
echo "'$handle'; " . gettype($handle) . "\n";
$read = fread($handle, 2096);
echo $read;
pclose($handle);
?>

Nota: Quando si abilita la modalità sicura, si può eseguire soltanto gli eseguibili presenti nella directory safe_mode_exec_dir. Per motivi pratici, attualmente, non ` permesso avere .. come componente del percorso di un eseguibile.

Avvertimento

Con la modalità sicura attivata, tutte le parole che seguono il comando iniziale sono trattate come argomenti. Quindi, echo y | echo x diventa echo "y | echo x".

Vedere anche pclose(), fopen() e proc_open().

readfile

(PHP 3, PHP 4, PHP 5)

readfile -- Invia un file

Descrizione

int readfile ( string filename [, bool use_include_path [, resource context]] )

Legge un file e lo scrive nello standard output.

Restituisce il numero di byte letti dal file. Se si verifica un errore viene restituito FALSE e se la funzione non è stata chiamata come @readfile(), un messaggio d'errore verra stampato.

Suggerimento: È possibile utilizzare una URL come un nome di file con questa funzione se fopen wrappers è stata abilitata. Per maggiori informazioni su come specificare i nomi di file vedere fopen() e Appendice M per avere la lista dei protocolli URL supportati.

Esempio 1. Esempio di uso di rename()
<?php rename("/tmp/tmp_file.txt", "/home/user/login/docs/my_file.txt"); ?>

Nota: Nelle versioni di PHP precedenti alla 4.3.3, la funzione rename() non può rinominare file attraverso partizioni nei sistemi *nix.

Nota: Dal PHP 5.0.0 rename() può anche essere utilizzata con qualche wrapper URL. Fare riferimento a Appendice M per avere l'elenco dei wrapper supportati da rename().

Nota: Il wrapper utilizzato per oldname DEVE essere il medesimo utilizzato per newname.

Nota: Il parametro context è stato aggiunto in PHP 5.0.0.

Vedere anche copy(), unlink() e move_uploaded_file().

rewind

(PHP 3, PHP 4, PHP 5)

rewind -- Riavvolge la posizione di un puntatore a file

Descrizione

bool rewind ( resource handle )

Pone l'indicatore alla posizione del file per handle all'inizio del flusso del file.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Il puntatore al file deve essere valido e deve puntare ad un file aperto con successo da fopen().

Nota: If you have opened the file in append ("a") mode, any data you write to the file will always be appended, regardless of the file position.

Vedere anche fseek() e ftell().

rmdir

(PHP 3, PHP 4, PHP 5)

rmdir -- Rimuove una directory

Descrizione

bool rmdir ( string dirname [, resource context] )

Tenta di cancellare la directory indiata da pathname. La directory deve essere vuota e i permessi concessi devono permetterlo. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Nota: Dal PHP 5.0.0 rmdir() può anche essere utilizzata con qualche wrapper URL. Fare riferimento a Appendice M per avere l'elenco dei wrapper supportati da rmdir().

Nota: Il parametro context è stato aggiunto in PHP 5.0.0.

Nota: Quando safe-mode è abilitato, PHP controlla che la directory nella quale si sta lavorando, abbia lo stesso UID dello script che è in esecuzione.

Vedere anche mkdir() e unlink().

set_file_buffer

(PHP 3 >= 3.0.8, PHP 4 >= 4.0.1, PHP 5)

set_file_buffer -- Alias di stream_set_write_buffer()

Descrizione

Questa funzione è un alias di stream_set_write_buffer().

stat

(PHP 3, PHP 4, PHP 5)

stat -- Da informazioni su un file

Descrizione

array stat ( string filename )

Restituisce una serie di informazioni a riguardo del file filename. Se il parametro filename è un link simbolico, le informazioni riguardano il file stesso, e non il file puntato dal link. La funzione lstat() è identica a stat() tranne che dovrebbe restituire il file puntato dal link.

In caso di errore stat() restituisce FALSE. Inoltre genera un warning.

La funzione restituisce un vettore con le informazioni sul file contenente i seguenti elementi. Il vettore parte dall'indice zero. Oltre agli indici numerici il vettore contiene indici associativi, come sarà indicato per ciascun parametro; questo è disponibile dal PHP versione 4.0.6.

Tabella 1. Formato del vettore restituito da stat() e fstat()

Indice numerico	Associativo (da PHP 4.0.6)	Descrizione
0	dev	device
1	ino	inode
2	mode	modalità di protezione dell'inode
3	nlink	numero di link
4	uid	ID utente del proprietario
5	gid	ID del gruppo del proprietario
6	rdev	tipo di device con l'inode device *
7	size	dimensione in byte
8	atime	ora dell'ultimo accesso (Unix timestamp)
9	mtime	ora del'ultima modifica (Unix timestamp)
10	ctime	ora dell'ultimo cambiamento di inode(Unix timestamp)
11	blksize	dimensione del blocco per l'I/O di filesystem *
12	blocks	numero dei blocchi allocati

* - valida solo su sistemi che supportano il tipo st_blksize--altri sistemi (ad esempio Windows) restituiscono -1.

Nota: I risultati di questa funzione saranno memorizzati. Vedere clearstatcache() per maggiori dettagli.

Suggerimento: A partire da PHP 5.0.0, questa funzione può essere utilizzata con alcuni URL wrappers. Fare riferimento a Appendice M per la lista di quali wrappers supportano le funzioni della famiglia stat().

Vedere anche lstat(), fstat(), filemtime() e filegroup().

symlink

(PHP 3, PHP 4, PHP 5)

symlink -- Crea un link simbolico

Descrizione

bool symlink ( string target, string link )

symlink() crea un link simbolico dal target esistente con il nome specificato da link.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Nota: Questa funzione non è implementata su piattaforme Windows

Vedere anche link() per creare hard link, e readlink() con linkinfo().

tempnam

(PHP 3, PHP 4, PHP 5)

tempnam -- Crea file con unico nome file

Descrizionen

string tempnam ( string dir, string prefix )

Crea un file con filename univoco nella directory specificata. Se la directory non esiste, tempnam() può generare un file in una directory temporanea di sistema, e restituire il nome di quest'ultima.

Precedentemente al PHP 4.0.6, il comportamento della funzione tempnam() dipendeva dal sistema. Su Windows il dispositivo di variabli TMP sovrascrive il dir parametro, su Linux la variabile TMPDIR ha la precedenza, mentre SVR4 utilizzerà sempre il parametro dir se la directory a cui punta, esiste. Consultare la vostra documentazione sulla funzione tempnam(3) in caso di dubbi.

Nota: Se PHP non può creare un file nello specificato dir parametro, ritorna al default di sistema.

Restituisce il nuovo nomefile temporaneo, o FALSE in caso di errore.
Esempio 1. tempnam() esempio
<?php $tmpfname = tempnam("/tmp", "FOO"); $handle = fopen($tmpfname, "w"); fwrite($handle, "writing to tempfile"); fclose($handle); // do here something unlink($tmpfname); ?>

Nota: Il funzionamento di questa funzione è cambiato nella 4.0.3. Il file temporaneo è creato inoltre èer evitare un conflitto dove il file dovrebbe apparire nel filesystem tra la volta in cui la stringa viene generata e prima che lo script tenti di creare il file. Notare che se si necessita cancellare il file, se non servisse più, non viene fatto automaticamente.

Vedere anche tmpfile() and unlink().

tmpfile

(PHP 3 >= 3.0.13, PHP 4, PHP 5)

tmpfile -- Crea un file temporaneo

Descrizione

resource tmpfile ( void )

Crea un file temporaneo con un nome univoco in modalità di lettura-scrittura (w+), restituendo un riferimento al file simile a quello tornato da fopen(). Il file viene automaticamente cancellato una volta chiuso (usando fclose()), o quando lo script termina.

Per dettagli, consulta la documentazione del tuo sistema sulla funzione tmpfile(3), così come il file haeader stdio.h.

Esempio 1. tmpfile() example
<?php $temp = tmpfile(); fwrite($temp, "writing to tempfile"); fseek($temp, 0); echo fread($temp, 1024); fclose($temp); // this removes the file ?>
Il precedente esempio visualizzerà:
writing toi tempfile

Vedere anche tempnam().

touch

(PHP 3, PHP 4, PHP 5)

touch -- Imposta l'ora di modifica di un file

Descrizione

bool touch ( string filename [, int time [, int atime]] )

Tenta di impostare l'ora di modifica del file indicato da filename. Se il parametro time non è passato, usa l'ora attuale. Ciò equivale a quello che fa utime (a volte indicato come utimes). Se è presente il terzo parametro opzionale atime è presente, viene utilizzato per impostare l'orario di accesso al file indicato. Occorre rilevare che l'orario di accesso è sempre modificato, indipendentemente dal numero dei parametri.

Se il file non esiste, viene creato.

Esempio 1. touch() example
<?php if (touch($FileName)) { echo "$FileName modification time has been changed to present time"; } else { echo "Sorry, could not change modification time of $FileName"; } ?>

umask

(PHP 3, PHP 4, PHP 5)

umask -- Cambia l'umask corrente

Descrizione

int umask ( [int mask] )

umask() imposta l'umask di PHP a mask & 0777 e restituisce il vecchio umask. Quando PHP è utilizzato come modulo server, l'umask viene ripristinato quando ciascuna richiesta è finita.

umask() senza argomenti restituisce semplicemente l'umask corrente.

unlink

(PHP 3, PHP 4, PHP 5)

unlink -- Cancella un file

Descrizione

bool unlink ( string filename [, resource context] )

Cancella filename. Simile alla funzione C di Unix unlink(). Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Nota: Dal PHP 5.0.0 unlink() potrà essere utilizzata anche con qualche wrapper URL. Fare riferimento a Appendice M per avere la lista di quali wrapper supportano unlink().

Nota: Il parametro context è stato aggiunto in PHP 5.0.0.

Restituisce 0 o FALSE in caso d'errore.

Vedere anche rmdir() per eliminare directory.

XXXIX. Funzioni Firebird/InterBase

Introduzione

Firebird/InterBase è un database relazionale che offre diverse features ANSI SQL-92 che gira su sistemi Linux, Windows, e su diverse piattaforma Unix. Firebird/InterBase offre un'eccellente meccanismo di concorrenza, alte performance, ed un potente linguaggio a supporto per le stored procedure ed i trigger. E' attivo in sistemi di produzione, sotto diversi nomi, dal 1981.

InterBase è il nome della versione protetta di questo RDBMS che fu sviluppata da Borland/Inprise. Maggiori informazioni su InterBase sono disponibili al link http://www.borland.com/interbase/.

Firebird è un progetto commercialmente indipendente di programmatori C e C++, tecnici, supporter che hanno sviluppato e migliorato un database relazionale multi-piattaforma basato sul codice sorgente rilasciato da Inprise Corp (ora nota come Borland Software Corp) under the InterBase Public License v.1.0 on 25 July, 2000. More information about Firebird is available at http://www.firebirdsql.org/.

Nota: Questo modulo supporta la versione 5 e successive di InterBase e tutte le versioni di Firebird. Il supporto per la versione 5.x di InterBase sarà rimosso dalla versione 5 di PHP.
Questo database usa il carattere di singolo apice (') come carattere di escape, un comportamento simile al database Sybase, aggiungere al proprio file php.ini la seguente direttiva:
magic_quotes_sybase = On

Requisiti

Installazione

Per abilitare l'utilizzo di InterBase, configurare il PHP con --with-interbase[=DIR], dove DIR indica la directory di installazione di InterBase; il defualt è /usr/interbase.

Nota per gli utenti Win32: Per abilitare questo modulo nel mondo Windows, occorre copiare gds32.dll dalla cartella DLL della distribuzione PHP/Win32 alla cartella SYSTEM32 della machhina Windows. (Ad esempio: C:\WINNT\SYSTEM32 o C:\WINDOWS\SYSTEM32). Nel caso in cui il server InterBase sia sulla medesima macchina in cui gira il PHP, queste DLL sono già installate. Quindi non occorre copiare gds32.dll dalla cartella DLL.

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

Tabella 1. Parametri di configurazione di InterBase

Nome	Default	Modificabile
ibase.allow_persistent	"On"	PHP_INI_SYSTEM
ibase.max_persistent	"-1"	PHP_INI_SYSTEM
ibase.max_links	"-1"	PHP_INI_SYSTEM
ibase.default_db	NULL	PHP_INI_SYSTEM
ibase.default_user	NULL	PHP_INI_ALL
ibase.default_password	NULL	PHP_INI_ALL
ibase.default_charset	NULL	PHP_INI_ALL
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

Per maggiori dettagli e definizioni delle costanti PHP_INI_* vedere ini_set().

Breve descrizione dei parametri di configurazione.

ibase.allow_persistent boolean: Stabilisce se permettere o meno le connessioni persistenti a Firebird/InterBase.
ibase.max_persistent integer: Indica il numero massimo di connessioni persistenti a Firebird/InterBase per processo. Le ulteriori connessioni create con ibase_pconnect() saranno non persistenti.
ibase.max_links integer: Indica il numero massimo di connessioni a Firebird/InterBase per processo, incluse le connessioni persistenti.
ibase.default_db string: Il database di default a cui connettersi quando viene chiamata la funzione ibase_[p]connect() senza specifica del nome del database. Se questo valore è impostato ed è abilitata la modalità sicura SQL, non saranno permesse connessioni ad altri database.
ibase.default_user string: Il nome utente da utilizzarsi per la connessione al database se non viene specificato.
ibase.default_password string: La password da utilizzare per connettersi al database se non viene specificata in fase di connessione.
ibase.default_charset string: Il set di caratteri da utilizzare per la connessione al database se non ne viene specificato uno al momento della connessione.
ibase.timestampformat string
ibase.dateformat string
ibase.timeformat string: Questo parametro è utilizzato per utilizzato per impostare il formato di data ed ora utilizzato per la restituzione di date ed ore dai set di risultati o per l'impostazione degli argomenti di data ed ora.

Tipi di risorse

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

Le seguenti costanti possono essere passate alle funzioni ibase_trans() per indicare il comportamento delle transazioni.

Tabella 2. Flag per le transazioni Firebird/InterBase

Costante	Descrizione
IBASE_DEFAULT	Sono utilizzate le impostazioni di default per la transazione. Quale default è determinato dalla libreria client, che, nella maggior parte dei casi, lo definisce come IBASE_WRITE\|IBASE_CONCURRENCY\|IBASE_WAIT.
IBASE_READ	Inizia una transazione di sola lettura.
IBASE_WRITE	Inizia una transazione di lettura/scrittura.
IBASE_CONSISTENCY	Inizia una transazione con il livello di isolamento impostato a 'consistency', il quale indica che una transazione non leggere da tabelle che stanno per essere modificate da altre transazioni concorrenti.
IBASE_CONCURRENCY	Inizia una transazione con il livello di isolamento impostato a 'concurrency' (o 'snapshot'), il quale indica che la transazione può accedere a tutte le tabelle, ma non può rilevare modifiche eseguite da altre transazioni dopo la partenza della transazione.
IBASE_COMMITTED	Inizia una transazione con il livello di isolamento impostato a 'read committed'. Questo flag dovrebbe essere abbinato con `IBASE_REC_VERSION` oppure con `IBASE_REC_NO_VERSION`. Questo livello di isolamento permette l'accesso alle modifiche quando queste vengono eseguite dopo l'inizio della transazione. Se si indica `IBASE_REC_NO_VERSION`, si può accedere solo all'ultima versione della riga. Se si indica `IBASE_REC_VERSION`, una riga può essere letta anche se vi è una modifica pendente da parte di una transazione concorrente.
IBASE_WAIT	Indica che la transazione deve attendere e riprovare in caso di conflitto.
IBASE_NOWAIT	Indica che la transazione deve fallire immadiatamente in caso di conflitto di accesso.

La seguenti costanti possono essere utilizzate con ibase_fetch_row(), ibase_fetch_assoc() o ibase_fetch_object() per indicare il comportamento nello scarico dei dati.

Tabella 3. Flag di scarico dati in Firebird/InterBase

Costante	Descrizione
IBASE_FETCH_BLOBS	Disponibile anche come `IBASE_TEXT` per compatibilità verso il passato. Forza lo scarico in linea dei contenuti BLOB, anzichè essere scaricati come indentificatori BLOB.
IBASE_FETCH_ARRAYS	Forza lo scarico in linea delle matrici. Altrimenti le matrici sarebbero restituite come variabili. La matrici possono essere utilizzate come argomenti solo per le operazioni di INSERT, poichè, al momento, non vi sono funzioni che trattano le matrici.
IBASE_UNIXTIME	Indica di restituire i dacmpi data e ora non come stringa, ma come UNIX timestamp (il numero dei secondi da una certa data, che è il 1-Gen-1970 0:00 UTC). Possono esserci problemi se utilizzato con date anteriori al 1970 su certi sistemi.

Le seguenti costanti sono utilizzate per passare richieste ed opzioni alle (ibase_server_info(), ibase_db_info (), ibase_backup(), ibase_restore () e ibase_maintain_db()). Fare riferimento ai manuali di Firebird/InterBase per avere il significato di queste funzioni.

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: Options to 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: Options to 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: Options to ibase_maintain_db()
IBASE_STS_DATA_PAGES
IBASE_STS_DB_LOG
IBASE_STS_HDR_PAGES
IBASE_STS_IDX_PAGES
IBASE_STS_SYS_RELATIONS: Options to 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: Opzioni per ibase_server_info()

Sommario
ibase_add_user -- Add a user to a security database (only for IB6 or later)
ibase_affected_rows -- Return the number of rows that were affected by the previous query
ibase_backup -- Initiates a backup task in the service manager and returns immediately
ibase_blob_add -- Aggiunge dati in un nuovo blob creato
ibase_blob_cancel -- Cancella la creazione di un blob
ibase_blob_close -- Chiude un blob
ibase_blob_create -- Crea un nuovo blob per aggiungerci dei dati
ibase_blob_echo -- Visualizza il contenuto di un blob sul browser
ibase_blob_get -- Ottiene len byte di dati dal blob aperto
ibase_blob_import -- Create un blob, copy il file al suo interno e lo chiude
ibase_blob_info -- Restituisce la lunghezza del blob e altre informazioni utlili
ibase_blob_open -- Apre un blob per ricavare parte di dati
ibase_close -- Chiude una connessione ad un database InterBase
ibase_commit_ret -- Commit a transaction without closing it
ibase_commit -- Esegue il commit di una transazione
ibase_connect -- Apre una connessione con un database InterBase
ibase_db_info -- Request statistics about a database
ibase_delete_user -- Delete a user from a security database (only for IB6 or later)
ibase_drop_db -- Drops a database
ibase_errcode -- Return an error code
ibase_errmsg -- Restituisce messaggi di errore
ibase_execute -- Esegue una query preparata in precedenza
ibase_fetch_assoc -- Fetch a result row from a query as an associative array
ibase_fetch_object -- Ottiene un oggetto da un database InterBase
ibase_fetch_row -- Elabora una riga da un database InterBase
ibase_field_info -- Ottiene informazioni su un campo
ibase_free_event_handler -- Cancels a registered event handler
ibase_free_query -- Libera la memoria allocata da una query preparata
ibase_free_result -- Libera la memoria allocata da un result set
ibase_gen_id -- Increments the named generator and returns its new value
ibase_maintain_db -- Execute a maintenance command on the database server
ibase_modify_user -- Modify a user to a security database (only for IB6 or later)
ibase_name_result -- Assigns a name to a result set
ibase_num_fields -- Ottiene il numero di campi in un result set
ibase_num_params -- Return the number of parameters in a prepared query
ibase_param_info -- Return information about a parameter in a prepared query
ibase_pconnect -- Crea una connessione persistente ad un database Interbase
ibase_prepare -- Prepara una query per un successivo binding dei segnaposto dei parametri ed esecuzione
ibase_query -- Esegue una query su di un database InterBase
ibase_restore -- Initiates a restore task in the service manager and returns immediately
ibase_rollback_ret -- Roll back a transaction without closing it
ibase_rollback -- Esegue il roll back di una transazione
ibase_server_info -- Request information about a database server
ibase_service_attach -- Connect to the service manager
ibase_service_detach -- Disconnect from the service manager
ibase_set_event_handler -- Register a callback function to be called when events are posted
ibase_timefmt -- Imposta il formato delle colonne timestamp, date e time restituite dalle query
ibase_trans -- Inizia una transazione
ibase_wait_event -- Wait for an event to be posted by the database

ibase_add_user

(PHP 4 >= 4.2.0, PHP 5)

ibase_add_user -- Add a user to a security database (only for IB6 or later)

Description

bool ibase_add_user ( resource service_handle, string user_name, string password [, string first_name [, string middle_name [, string last_name]]] )

PHP 4 uses server, dba_user_name and dba_user_password instead of service_handle parameter.

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

ibase_affected_rows

(PHP 5)

ibase_affected_rows -- Return the number of rows that were affected by the previous query

bool ibase_blob_echo ( string blob_id )

Questa funzione apre un BLOB in lettura ed invia il suo contenuto direttamente allo standard output (prevalentemente il browser). Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche ibase_blob_open(), ibase_blob_close() e ibase_blob_get().

ibase_blob_get

(PHP 3 >= 3.0.7, PHP 4, PHP 5)

ibase_blob_get -- Ottiene len byte di dati dal blob aperto

Descrizione

string ibase_blob_get ( resource blob_handle, int len )

Questa funzine restituisce almeno len bytes da un BLOB che è stato aperto in lettura con ibase_blob_open(). Restituisce FALSE se si verifica un errore.

<?php
    $sql       = "SELECT blob_value FROM table";
    $result    = ibase_query($sql);
    $data      = ibase_fetch_object($result);
    $blob_data = ibase_blob_info($data->BLOB_VALUE);
    $blob_hndl = ibase_blob_open($data->BLOB_VALUE);
    echo         ibase_blob_get($blob_hndl, $blob_data[0]);
?>

Questo esempio non fa altro che 'ibase_blob_echo($data->BLOB_VALUE)', mostra come ottenere le informazioni in una variabile $variable da manipolare a piacere.

Nota: Non è possibile leggere da un BLOB che è stato aperto in scrittura da ibase_blob_create().

Vedere anche ibase_blob_open(), ibase_blob_close() e ibase_blob_echo().

ibase_blob_import

(PHP 3 >= 3.0.7, PHP 4, PHP 5)

ibase_blob_import -- Create un blob, copy il file al suo interno e lo chiude

Descrizione

string ibase_blob_import ( [resource link_identifier, resource file_handle] )

Questa funzione crea un BLOB e vi inserisce un file intero, lo chiude e restituisce l'id assegnato al BLOB. file_handle è un puntatore di file restituito da fopen(). La funzione restituisce FALSE se si verifica un errore.

Vedere anche ibase_blob_add(), ibase_blob_cancel(), ibase_blob_close() e ibase_blob_create().

ibase_blob_info

(PHP 3 >= 3.0.7, PHP 4, PHP 5)

ibase_blob_info -- Restituisce la lunghezza del blob e altre informazioni utlili

bool ibase_commit_ret ( [resource link_or_trans_identifier] )

If called without an argument, this function commits the default transaction of the default link. If the argument is a connection identifier, the default transaction of the corresponding connection will be committed. If the argument is a transaction identifier, the corresponding transaction will be committed. The transaction context will be retained, so statements executed from within this transaction will not be invalidated. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

ibase_commit

(PHP 3 >= 3.0.7, PHP 4, PHP 5)

ibase_commit -- Esegue il commit di una transazione

Descrizione

bool ibase_commit ( [resource link_identifier] )

Se chiamata senza parametri, la funzione esegue il commit della transazione di default, sul link di default. Se l'argomento identifica una transazione, verrà aseguito il commit della transazione di default su quella connessione. Se l'argomento identifica una transazione verrà eseguito il commit della transazione. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

ibase_connect

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

ibase_connect -- Apre una connessione con un database InterBase

Descrizione

resource ibase_connect ( string database [, string username [, string password [, string charset [, int buffers [, int dialect [, string role]]]]]] )

Stabilisce una connessione con un server InterBase. Il parametro database deve essere un percorso valido di un file di database sul server dove risiede. Se il server non fosse locale, bisogna aggiungere prima del percorso o 'hostname:' (TCP/IP), o '//hostname/' (NetBEUI) o 'hostname@' (IPX/SPX), in base al protocollo di connessione utilizzato. username e password possono venire specificati anche con le direttive di configurazione del PHP ibase.default_user e ibase.default_password. charset è il set di caratteri predefinito per un database. buffers è il numero di buffer di database da allocare per la cache dal lato server. Se è 0 o viene omesso, il server usa il suo valore predefinito. dialect seleziona il dialetto SQL predefinito per ogni operazione eseguita all'interno di una connessione, e il suo valore predefinito è il più alto supportato dalle librerie del client.

Nel caso di una seconda chiamata fatta con ibase_connect() con gli stessi parametri, non verrà creato alcun nuovo collegamento, bensì, l'identificatore del collegamento già aperto verrà restituito. Il collegamento al server verrà chiuso appena termina l'esecuzione dello script, a meno che non venga chiuso prima esplicitamente chiamando ibase_close().
Esempio 1. Esempio di ibase_connect()
<?php $host = 'localhost:/path/to/your.gdb'; $dbh = ibase_connect($host, $username, $password); $stmt = 'SELECT * FROM tblname'; $sth = ibase_query($dbh, $stmt); while ($row = ibase_fetch_object($sth)) { echo $row->email . "\n"; } ibase_free_result($sth); ibase_close($dbh); ?>

Nota: Il parametro opzionale buffers è stato aggiunto in PHP 4.0.0.

Nota: dialect è stato aggiunto in PHP 4.0.0. E' funzionante solo con InterBase 6 e versioni successive.

Nota: role è stato aggiunto in PHP 4.0.0. E' funzionante solo con InterBase 5 e versioni successive.

Nota: Se si verificano degli errori tipo "arithmetic exception", "numeric overflow", oppure "string truncation. Cannot transliterate character between character sets" (questo capita quando si tenta di usare dei caratteri accentati) questa funzione o dopo la funzione ibase_query(), occorre impostare il set di caratteri (ad esempio ISO8859_1 oppure il set di caratteri corrente).

Vedere anche: ibase_pconnect() e ibase_close().

ibase_db_info

(PHP 5)

ibase_db_info -- Request statistics about a database

Description

string ibase_db_info ( resource service_handle, string db, int action [, int argument] )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

ibase_delete_user

(PHP 4 >= 4.2.0, PHP 5)

ibase_delete_user -- Delete a user from a security database (only for IB6 or later)

Description

bool ibase_delete_user ( resource service_handle, string user_name )

PHP 4 uses server, dba_user_name and dba_user_password instead of service_handle parameter.

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

ibase_drop_db

(PHP 5)

ibase_drop_db -- Drops a database

Description

bool ibase_drop_db ( [resource connection] )

This functions drops a database that was opened by either ibase_connect() or ibase_pconnect(). The database is closed and deleted from the server. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

ibase_errcode

(PHP 5)

ibase_errcode -- Return an error code

Description

int ibase_errcode ( void )

Returns the error code that resulted from the most recent InterBase function call. Returns FALSE if no error occurred.

ibase_errmsg

(PHP 3 >= 3.0.7, PHP 4, PHP 5)

ibase_errmsg -- Restituisce messaggi di errore

Descrizione

string ibase_errmsg ( void )

Restituisce una stringa contenente un messaggio di errore dalla più recente funzione InterBse eseguita. La funzione restituisce FALSE se non vi sono errori.

Vedere anche ibase_errcode().

ibase_execute

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

ibase_execute -- Esegue una query preparata in precedenza

Descrizione

resource ibase_execute ( resource query [, int bind_args] )

Esegue una query preparata da ibase_prepare(). Se la query genera un errore, la funzione restituisce FALSE. Se invece ha successo ed si ha un set di risultati (tipo un query SELECT), la funzione ne restituisce l'identificativo. Se la query ha successo e non vi sono risultati, restituisce TRUE

Ciò è molto più efficace che usare ibase_query() se state ripetendo uno stesso tipo di query molte volte cambiando solo alcuni parametri.

Esempio 1. Esempio di uso di ibase_execute()
<?php $dbh = ibase_connect($host, $username, $password); $updates = array( 1 => 'Eric', 5 => 'Filip', 7 => 'Larry' ); $query = ibase_prepare($dbh, "UPDATE FOO SET BAR = ? WHERE BAZ = ?"); while (list($baz, $bar) = each($updates)) { ibase_execute($query, $bar, $baz); } ?>

Nota: In PHP 5.0.0 e successivi, questa funzione restituisce il numero di righe toccate dalla query (se >0 ed è applicabile al tipo di query). Una query che ha successo, ma che non modifica nessuna righa (ad esempio un UPDATE su record che non esistono) restituirà TRUE

Vedere anche ibase_query().

ibase_fetch_assoc

(PHP 4 >= 4.3.0, PHP 5)

ibase_fetch_assoc -- Fetch a result row from a query as an associative array

Description

array ibase_fetch_assoc ( resource result [, int fetch_flag] )

ibase_fetch_assoc() returns an associative array that corresponds to the fetched row. Subsequent calls will return the next row in the result set, or FALSE if there are no more rows.

ibase_fetch_assoc() fetches one row of data from the result. 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 ibase_fetch_row() or use alias names in your query.

fetch_flag is a combination of the constants IBASE_TEXT and IBASE_UNIXTIME ORed together. Passing IBASE_TEXT will cause this function to return BLOB contents instead of BLOB ids. Passing IBASE_UNIXTIME will cause this function to return date/time values as Unix timestamps instead of as formatted strings.

ibase_fetch_object

(PHP 3 >= 3.0.7, PHP 4, PHP 5)

ibase_fetch_object -- Ottiene un oggetto da un database InterBase

Descrizione

object ibase_fetch_object ( resource result_id [, int fetch_flag] )

Elabora una riga come un pseudo-oggetto da un result_id ottenuto o da ibase_query() o da ibase_execute().

<?php
    $dbh = ibase_connect($host, $username, $password);
    $stmt = 'SELECT * FROM tblname';
    $sth = ibase_query($dbh, $stmt);
    while ($row = ibase_fetch_object($sth)) {
        echo $row->email . "\n";
    }
    ibase_close($dbh);
?>

Chiamate successive a ibase_fetch_object() restituiscono la successiva riga dai risultati della query o FALSE se non vi sono ulteriori righe.

Il parametro fetch_flag è una combinazione delle costanti IBASE_TEXT e IBASE_UNIXTIME con l'operatore OR. Passando IBASE_TEXT si forza questa funzione a resituire il contenuto del BLOB anzichè l'identificatore del BLOB. Passando IBASE_UNIXTIME si forza la funzione a restituire i valori di data/ora com Unix timestamp anzichè come stringa formattata.

Vedere anche ibase_fetch_row() e ibase_fetch_assoc().

ibase_fetch_row

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

ibase_fetch_row -- Elabora una riga da un database InterBase

Descrizione

array ibase_fetch_row ( int result_identifier )

Restituisce un array che corrisponde alla riga ottenuta o FALSE se non ci sono righe rimanenti.

ibase_fetch_row() prende una riga di dati dai risultati associati allo specificato result_identifier. La riga viene restituita come un array. Ogni colonna risultante viene immagazzinata in un offset dell'array, l'offset inizia da 0.

Chiamate successive a ibase_fetch_row() restituiscono la successiva riga dai risultati della query o FALSE se non vi sono ulteriori righe.

ibase_field_info

(PHP 3 >= 3.0.7, PHP 4, PHP 5)

ibase_field_info -- Ottiene informazioni su un campo

Descrizione

array ibase_field_info ( int result, int field number )

Restituisce un array con informazioni relative a un campo dopo che una query select è stata eseguita. L'array ha la forma name, alias, relation, length e type.

$rs=ibase_query("SELECT * FROM tablename"); 
$coln = ibase_num_fields($rs);
for ($i=0; $i < $coln; $i++) {
    $col_info = ibase_field_info($rs, $i); 
    echo "name: ".$col_info['name']."\n"; 
    echo "alias: ".$col_info['alias']."\n"; 
    echo "relation: ".$col_info['relation']."\n"; 
    echo "length: ".$col_info['length']."\n"; 
    echo "type: ".$col_info['type']."\n"; 
    }

ibase_free_event_handler

(PHP 5)

ibase_free_event_handler -- Cancels a registered event handler

Description

bool ibase_free_event_handler ( resource event )

This function causes the registered event handler specified by event to be cancelled. The callback function will no longer be called for the events it was registered to handle. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

ibase_free_query

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

ibase_free_query -- Libera la memoria allocata da una query preparata

Descrizione

int ibase_free_query ( int query )

Libera una query preparata da ibase_prepare().

ibase_free_result

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

ibase_free_result -- Libera la memoria allocata da un result set

Descrizione

int ibase_free_result ( int result_identifier )

Libera un result set che è stato creato da ibase_query().

ibase_gen_id

(PHP 5)

ibase_gen_id -- Increments the named generator and returns its new value

Description

mixed ibase_gen_id ( string generator [, int increment [, resource link_identifier]] )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Returns new generator value as integer, or as string if the value is too big.

ibase_maintain_db

(PHP 5)

ibase_maintain_db -- Execute a maintenance command on the database server

Description

bool ibase_maintain_db ( resource service_handle, string db, int action [, int argument] )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

ibase_modify_user

(PHP 4 >= 4.2.0, PHP 5)

ibase_modify_user -- Modify a user to a security database (only for IB6 or later)

Description

bool ibase_modify_user ( resource service_handle, string user_name, string password [, string first_name [, string middle_name [, string last_name]]] )

PHP 4 uses server, dba_user_name and dba_user_password instead of service_handle parameter.

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

ibase_name_result

(PHP 5)

ibase_name_result -- Assigns a name to a result set

Description

bool ibase_name_result ( resource result, string name )

This function assigns a name to a result set. This name can be used later in UPDATE|DELETE ... WHERE CURRENT OF name statements. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

<?php
 $result = ibase_query("SELECT field1,field2 FROM table FOR UPDATE");
    ibase_name_result($result, "my_cursor");

    $updateqry = ibase_prepare("UPDATE table SET field2 = ? WHERE CURRENT OF my_cursor");

    for ($i = 0; ibase_fetch_row($result); ++$i) {
        ibase_execute($updateqry, $i);
    }
?>

ibase_num_fields

(PHP 3 >= 3.0.7, PHP 4, PHP 5)

ibase_num_fields -- Ottiene il numero di campi in un result set

Descrizione

int ibase_num_fields ( int result_id )

Restituisce un integer contenente il numero di campi in un result set.

<?php
       $dbh = ibase_connect ($host, $username, $password);
       $stmt = 'SELECT * FROM tblname';
       $sth = ibase_query ($dbh, $stmt);

       if (ibase_num_fields($sth) > 0) {
       while ($row = ibase_fetch_object ($sth)) {
       print $row->email . "\n";
       }
       } else {
       die ("Nessun result è stato trovato per la tua query");
       }

       ibase_close ($dbh);
       ?>

Vedere anche: ibase_field_info().

ibase_num_params

(PHP 5)

ibase_num_params -- Return the number of parameters in a prepared query

Description

int ibase_num_params ( resource query )

This function returns the number of parameters in the prepared query specified by query. This is the number of binding arguments that must be present when calling ibase_execute().

ibase_param_info

(PHP 5)

ibase_param_info -- Return information about a parameter in a prepared query

Description

array ibase_param_info ( resource query, int param_number )

Returns an array with information about a parameter after a query has been prepared. The array is in the form of name, alias, relation, length, type.

ibase_pconnect

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

ibase_pconnect -- Crea una connessione persistente ad un database Interbase

Descrizione

int ibase_pconnect ( string database [, string username [, string password [, string charset [, int buffers [, int dialect [, string role]]]]]] )

ibase_pconnect() agisce in modo molto simile a ibase_connect() con due differenze principali. Innanzitutto, durante la connessione, la funzione cercherà prima di trovare un collegamento (persistente) che è già stato aperto con gli stessi parametri. Se viene trovato, il suo identificatore verrà restituito al posto di aprire una nuova connessione. In secondo luogo, la connessione al server InterBase non verrà chiusa al termine dell'esecuzione dello script. Invece, il collegamento resterà aperto per un uso futuro (ibase_close() non chiuderà i collegamenti stabiliti da ibase_pconnect()). Questo tipo di collegamento è perciò chiamato 'persistente'.

Nota: buffers è stato aggiunto in PHP4-RC2.

Nota: dialect è stato aggiunto in PHP4-RC2. Funziona soltanto con InterBase 6 e superiori.

Nota: role è stato aggiunto in PHP4-RC2. Funziona soltanto con InterBase 5 e superiori.

Vedere anche ibase_connect() per il significato dei parametri passati a questa funzione. Sono esattamente gli stessi.

ibase_prepare

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

ibase_prepare -- Prepara una query per un successivo binding dei segnaposto dei parametri ed esecuzione

Descrizione

int ibase_prepare ( [int link_identifier, string query] )

Prepara una query per un successivo binding dei segnaposto dei parametri ed esecuzione (tramite ibase_execute()).

ibase_query

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

ibase_query -- Esegue una query su di un database InterBase

Descrizione

int ibase_query ( [int link_identifier, string query [, int bind_args]] )

Esegue una query su di un database InterBase. Se la query non ha successo, restituisce FALSE. Se ha successo e vi sono riga di risultato (come si ha ad esempio con le query SELECT), restituisce un identificatore di risorsa. Se la query ha avuto successo, ma non ci sono risultati, restituisce TRUE. Restutuisce FALSE se la query fallisce.

Vedere anche ibase_errmsg(), ibase_fetch_row(), ibase_fetch_object() e ibase_free_result().

ibase_restore

(PHP 5)

ibase_restore -- Initiates a restore task in the service manager and returns immediately

Description

mixed ibase_restore ( resource service_handle, string source_file, string dest_db [, int options [, bool verbose]] )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

ibase_rollback_ret

(PHP 5)

ibase_rollback_ret -- Roll back a transaction without closing it

Description

bool ibase_rollback_ret ( [resource link_or_trans_identifier] )

If called without an argument, this function rolls back the default transaction of the default link. If the argument is a connection identifier, the default transaction of the corresponding connection will be rolled back. If the argument is a transaction identifier, the corresponding transaction will be rolled back. The transaction context will be retained, so statements executed from within this transaction will not be invalidated. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

ibase_rollback

(PHP 3 >= 3.0.7, PHP 4, PHP 5)

ibase_rollback -- Esegue il roll back di una transazione

resource ibase_set_event_handler ( callback event_handler, string event_name1 [, string event_name2 [, string ...]] )

resource ibase_set_event_handler ( resource connection, callback event_handler, string event_name1 [, string event_name2 [, string ...]] )

This function registers a PHP user function as event handler for the specified events. The callback is called with the event name and the link resource as arguments whenever one of the specified events is posted by the database. The callback must return FALSE if the event handler should be canceled. Any other return value is ignored. This function accepts up to 15 event arguments.

<?php

function event_handler($event_name, $link) 
{
    if ($event_name=="NEW ORDER") {
        // process new order
        ibase_query($link, "UPDATE orders SET status='handled'");
    } else if ($event_name=="DB_SHUTDOWN") {
        // free event handler 
        return false;
    }
}

ibase_set_event_handler($link, "event_handler", "NEW_ORDER", "DB_SHUTDOWN");
?>

The return value is an event resource. This resource can be used to free the event handler using ibase_free_event_handler().

ibase_timefmt

(PHP 3 >= 3.0.6, PHP 4)

ibase_timefmt -- Imposta il formato delle colonne timestamp, date e time restituite dalle query

Descrizione

int ibase_timefmt ( string format [, int columntype] )

Imposta il formato delle colonne di tipo timestamp, date o time restituite dalle query. Internamente, le colonne vengono formattate dalla funzione C strftime(), quindi fate riferimento alla sua documentazione riguardo al formato della stringa. columntype è una delle costanti IBASE_TIMESTAMP, IBASE_DATE e IBASE_TIME. Se omessa, è predefinita a IBASE_TIMESTAMP per motivi di compatibilità con il passato.

<?php
       // Le colonne di tipo TIME di InterBase vengono restituite nella
       // forma '05 hours 37 minutes'. 
       ibase_timefmt("%H hours %M minutes", IBASE_TIME);
       ?>

Potete impostare anche valori predefiniti per questi formati con la direttiva di configurazione ibase.timestampformat, ibase.dateformat e ibase.timeformat.

Nota: columntype è stata aggiunta in PHP 4.0. Ha significato solo con InterBase versione 6 e successive.

Nota: Un'incompatibilità con il passato si è avuta nel PHP 4.0 quando la direttiva di configurazione del PHP ibase.timeformat è stata rinominata in ibase.timestampformat e la direttiva ibase.dateformat e ibase.timeformat sono state aggiunte, così che i loro nomi fossero più simili alle loro funzionalità.

ibase_trans

(PHP 3 >= 3.0.7, PHP 4, PHP 5)

ibase_trans -- Inizia una transazione

Descrizione

int ibase_trans ( [int trans_args [, int link_identifier]] )

Inizia una transazione.

ibase_wait_event

(PHP 5)

ibase_wait_event -- Wait for an event to be posted by the database

Description

string ibase_wait_event ( string event_name1 [, string event_name2 [, string ...]] )

string ibase_wait_event ( resource connection, string event_name1 [, string event_name2 [, string ...]] )

This function suspends execution of the script until one of the specified events is posted by the database. The name of the event that was posted is returned. This function accepts up to 15 event arguments.

XL. Firebird/Interbase Functions (PDO_FIREBIRD)

Introduzione

Avvertimento

PDO_FIREBIRD is a driver that implements the PHP Data Objects (PDO) interface to enable access from PHP to Firebird and Interbase databases.

Sommario
PDO_FIREBIRD DSN -- Connecting to Firebird and Interbase databases

PDO_FIREBIRD DSN

(no version information, might be only in CVS)

PDO_FIREBIRD DSN -- Connecting to Firebird and Interbase databases

Descrizione

The PDO_FIREBIRD Data Source Name (DSN) is composed of the following elements:

DSN prefix: The DSN prefix is firebird:.
DataSource: The hostname on which the database server resides.
Port: The port number for the server on which the database is running.
Database: The name of the database.
User: The name of the user that will connect to the database.
Password: The password for the user.

Esempi

Esempio 1. PDO_FIREBIRD DSN examples
The following example shows a PDO_FIREBIRD DSN for connecting to Firebird and Interbase databases:
firebird:User=john;Password=mypass;Database=DATABASE.GDE;DataSource=localhost;Port=3050

XLI. Funzioni FriBiDi

Introduzione

FriBiDi è un'implementazione free del Unicode Bidirectional Algorithm.

Requisiti

Occorre scaricare ed installare il pacchetto FriBiDi.

Installazione

Per abilitare il supporto FriBiDi in PHP occorre compilare il PHP con l'opzione --with-fribidi[=DIR], dove DIR indica la directory di installazione di FriBiDi.

Gli utenti di Windows, per potere utilizzare queste funzioni, devono abilitare php_fribidi.dll dal php.ini. You may download this PECL extension DLL from the PHP Downloads page or at http://snaps.php.net/.

Configurazione di Runtime

Tipi di risorse

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

FRIBIDI_CHARSET_UTF8 (integer)
FRIBIDI_CHARSET_8859_6 (integer)
FRIBIDI_CHARSET_8859_8 (integer)
FRIBIDI_CHARSET_CP1255 (integer)
FRIBIDI_CHARSET_CP1256 (integer)
FRIBIDI_CHARSET_ISIRI_3342 (integer)

Sommario
fribidi_log2vis -- Converte una stringa logica in una visuale

fribidi_log2vis

(PHP 4 >= 4.0.4, PECL)

fribidi_log2vis -- Converte una stringa logica in una visuale

Descrizione

string fribidi_log2vis ( string str, string direction, int charset )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

XLII. FrontBase Functions

Introduzione

Queste funzioni permettono di accedere ai servers del database FrontBase. Maggiori informazioni su FrontBase: http://www.frontbase.com/.

Documentazione su FrontBase : http://www.frontbase.com/cgi-bin/WebObjects/FrontBase.woa/wa/productsPage?currentPage=Documentation.

Il supporto Frontbase è stato aggiunto dal PHP 4.0.6.

Requisiti

Per potere utilizzare queste funzioni occorre installare o il server FrontBase o, al limite, le librerie fbsql client. Si può ottenere FrontBase da http://www.frontbase.com/.

Installazione

Affinché queste funzioni siano disponibili è necessario compilare php con il supporto fbsql usando l' opzione --with-fbsql[=DIR].Se si usa questa opzione senza specificare il percorso a fbsql, php cercherà le librerie client di fbsql nella cartella di default specificata nell'istallazione di FrontBase, a seconda del sistema operativo. Se si installa FrontBase in una cartella non standard è necessario specificare sempre il percorso a fbsql: --with-fbsql=/path/to/fbsql. In questo modo si forzerà php ad usare le librerie client installate da FrontBase, evitando ogni conflitto.

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

Tabella 1. Opzioni di configurazione per FrontBase

Nome	Default	Modificabile
fbsql.allow_persistent	"1"	PHP_INI_SYSTEM
fbsql.generate_warnings	"0"	PHP_INI_SYSTEM
fbsql.autocommit	"1"	PHP_INI_SYSTEM
fbsql.max_persistent	"-1"	PHP_INI_SYSTEM
fbsql.max_links	"128"	PHP_INI_SYSTEM
fbsql.max_connections	"128"	PHP_INI_SYSTEM
fbsql.max_results	"128"	PHP_INI_SYSTEM
fbsql.batchSize	"1000"	PHP_INI_SYSTEM
fbsql.default_host	NULL	PHP_INI_SYSTEM
fbsql.default_user	"_SYSTEM"	PHP_INI_SYSTEM
fbsql.default_password	""	PHP_INI_SYSTEM
fbsql.default_database	""	PHP_INI_SYSTEM
fbsql.default_database_password	""	PHP_INI_SYSTEM

Per maggiori dettagli e per le definizioni delle costanti PHP_INI_* vedere ini_set().

Tipi di risorse

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

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)

Sommario
fbsql_affected_rows -- Restituisce il numero di righe (tuple) interessate nella precedente operazione di FrontBase
fbsql_autocommit -- Abilita o disabilita autocommit
fbsql_blob_size -- Get the size of a BLOB
fbsql_change_user -- Cambia l'identità dell'utente connesso con una connessione attiva
fbsql_clob_size -- Get the size of a CLOB
fbsql_close -- Chiude la connessione a FrontBase
fbsql_commit -- Compie una transazione
fbsql_connect -- Apre una connessione al Server FrontBase
fbsql_create_blob -- Crea un BLOB
fbsql_create_clob -- Crea un CLOB
fbsql_create_db -- Crea un database
fbsql_data_seek -- Sposta il puntatore del risultato interno
fbsql_database_password -- Imposta o ricerca la password di un database FrontBase.
fbsql_database -- Imposta oppure ottiene il nome del database usato per la connessione
fbsql_db_query -- Manda una query FrontBase
fbsql_db_status -- Restituisce lo stato di un dato database.
fbsql_drop_db -- Cancella un database FrontBase
fbsql_errno -- Ritorna il valore numerico del messaggio di errore emesso dalla precedente operazione FrontBase.
fbsql_error -- Ritorna il testo del messaggio di errore emesso dalla precedente operazione FrontBase.
fbsql_fetch_array -- Restituisce una riga (tupla) di risultato in forma di Array associativo, Array enumerato o entrambi
fbsql_fetch_assoc -- Restituisce una riga (tupla) di risultato in forma di Array associativo.
fbsql_fetch_field -- Ottiene informazioni su una colonna da un set di risultati come oggetto
fbsql_fetch_lengths -- Ottiene la lunghezza di ciascun output in un set di risultati
fbsql_fetch_object -- Resituisce un riga da un set di risultati come oggetto
fbsql_fetch_row -- Ottiene una riga come matrice numerata
fbsql_field_flags -- Ottiene i flag associati al campo specificato
fbsql_field_len -- Restituisce la lunghezza di un campo
fbsql_field_name -- Restituisce il nome del campo specificato
fbsql_field_seek -- Imposta il puntatore del set di risultati ad un specifico indice di campo
fbsql_field_table -- Ottiene il nome della tabella in cui si trova il campo
fbsql_field_type -- Ottiene il tipo del campo specificato
fbsql_free_result -- Libera la memoria da un set di risultati
fbsql_get_autostart_info -- Nessuna descrizione fornita, per ora
fbsql_hostname -- Ottiene o imposta il nome del server per la connessione
fbsql_insert_id -- restituisce l'id generato dalla precedente operazione di INSERT
fbsql_list_dbs -- Elenca i database presenti su un server FrontBase
fbsql_list_fields -- Elenca i campi di un set di risultati
fbsql_list_tables -- Elenxa le tabelle presenti in un database FrontBase
fbsql_next_result -- Muove il puntatore interno al risultato successivo
fbsql_num_fields -- Ottiene il numero dei campi presenti in un set di risultati
fbsql_num_rows -- Restituisce il numero di righe presenti in un set di risultati
fbsql_password -- Ottiene o imposta la password per la connessione
fbsql_pconnect -- Apre una connessione persistente ad un server FrontBase
fbsql_query -- Invia una query a FrontBase
fbsql_read_blob -- Legge un BLOB dal database
fbsql_read_clob -- Legge un CLOB dal database
fbsql_result -- Restituisce i dati di una query
fbsql_rollback -- Esegue il rollback della transazione
fbsql_select_db -- Seleziona un database FrontBase
fbsql_set_lob_mode -- Imposta la modalità LOB in un set di risultati FrontBase
fbsql_set_password -- Change the password for a given user
fbsql_set_transaction -- Imposta i lock e l'isolamento delle transazioni
fbsql_start_db -- Attiva un database locale o remoto
fbsql_stop_db -- Ferma un database locale o remoto
fbsql_tablename -- Restituisce il nome della tabella dei campi
fbsql_username -- Ottiene o imposta l'utente per la connessione
fbsql_warnings -- Abilita o disabilita i warnings FrontBase

fbsql_affected_rows

(PHP 4 >= 4.0.6, PHP 5)

fbsql_affected_rows -- Restituisce il numero di righe (tuple) interessate nella precedente operazione di FrontBase

Descrizione

int fbsql_affected_rows ( [int link_identifier] )

fbsql_affected_rows() restituisce il numero di righe interessate dall'ultima query INSERT, UPDATE or DELETE associata al parametro link_identifier. Se tale parametro non è stato specificato, sarà usata l'ultima connessione aperta da fbsql_connect().

Nota: Se si stanno usando le transazioni, è necessario chiamare la funzione fbsql_affected_rows() dopo una query INSERT, UPDATE, or DELETE, non dopo la chiusura della transazione (commit).

Se l'ultima query è un istruzione DELETE senza clausola WHERE, tutte le righe verranno cancellate dalla tabella e la funzione restituirà il valore 0 (zero).

Nota: Se si utilizza l'istruzione UPDATE, FrontBase non aggiornerà le colonne in cui il valore nuovo è uguale a quello vecchio. Quindi esiste la possibilità che fbsql_affected_rows() sia diverso dal numero di righe realmente interessate dalla query.

fbsql_change_user() Cambia l'identità dell'utente connesso con una connessione attiva, o con la connessione specificata dal parametro opzionale link_identifier. Se è stato specificato un database, dopo che l'identità dell'utente sarà stata cambiata, questo diventerà il database attivo . Se l'autorizzazione del nuovo utente fallisce, rimarrà attiva l'identità dell'utente corrente.

fbsql_clob_size

(PHP 4 >= 4.2.0, PHP 5)

fbsql_clob_size -- Get the size of a CLOB

Descrizione

int fbsql_clob_size ( string clob_handle [, resource link_identifier] )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

fbsql_close

(PHP 4 >= 4.0.6, PHP 5)

fbsql_close -- Chiude la connessione a FrontBase

Descrizione

boolean fbsql_close ( [resource link_identifier] )

Restituisce: TRUE in caso di successo, FALSE in caso di fallimento.

fbsql_close() chiude la connessione al server FrontBase associata ad uno specificato link identifier. Se il link_identifier non fosse specificato, verrebbe chiusa l'ultima connessione aperta.

Non è sempre necessario usare fbsql_close() nel caso di connessioni non permanenti, esse verranno chiuse automaticamente alla fine dell'esecuzione dello script.

Esempio 1. Uso di fbsql_close()

<?php
    $link = fbsql_connect ("localhost", "_SYSTEM", "secret")
        or die ("Could not connect");
    print ("Connected successfully");
    fbsql_close ($link);
?>

Vedere anche: fbsql_connect() e fbsql_pconnect().

fbsql_commit

(PHP 4 >= 4.0.6, PHP 5)

fbsql_commit -- Compie una transazione

Descrizione

bool fbsql_commit ( [resource link_identifier] )

restituisce: TRUE in caso di successo, FALSE in caso di fallimento.

fbsql_commit() esegue la transazione corrente scrivendo tutti gli aggiornamenti pendenti, cancella il disco e sblocca tutte le righe della tabella bloccata dalla transazione. Questo comando è necessario solo nel caso in cui autocommit fosse impostato su false.

Vedere anche: fbsql_autocommit() e fbsql_rollback()

fbsql_connect

(PHP 4 >= 4.0.6, PHP 5)

fbsql_connect -- Apre una connessione al Server FrontBase

Descrizione

resource fbsql_connect ( [string hostname [, string username [, string password]]] )

Restituisce un valore di link_identifier positivo in caso di successo, o un messaggio di errore in caso di fallimento.

fbsql_connect() Apre una connessione al Server FrontBase.Se i parametri opzionali non sono specificati verranno usati i valori seguenti come default: hostname = 'NULL', username = '_SYSTEM' e password = empty password.

Se si richiamasse, una seconda volta, la funzione fbsql_connect() con gli stessi argomenti, non si creerebbe una nuova connessione,ma verrebbe restituito il valore di link_identifier della connessione già aperta.

La connessione al server si chiuderà alla fine dello script, a meno che non venga chiusa in anticipo richiamando esplicitamente la funzione fbsql_close().

Esempio 1. fbsql_connect()

<?php

    $link = fbsql_connect ("localhost", "_SYSTEM", "secret")
        or die ("Could not connect");
    print ("Connected successfully");
    fbsql_close ($link);

?>

Vedere anche fbsql_pconnect() e fbsql_close().

fbsql_create_blob

(PHP 4 >= 4.2.0, PHP 5)

fbsql_create_blob -- Crea un BLOB

Descrizione

string fbsql_create_blob ( string blob_data [, resource link_identifier] )

Restituisce un handle al blob appena creato.

La funzione fbsql_create_blob() crea un campo blob a partire da blob_data. L'handle restituito può essere utilizzato con i comandi di inserimento e di aggiornamento dei blob nel database.

Esempio 1. Esempio di uso di fbsql_create_blob()

<?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);
?>

Vedere anche: fbsql_create_clob(), fbsql_read_blob(), fbsql_read_clob() e fbsql_set_lob_mode().

fbsql_create_clob

(PHP 4 >= 4.2.0, PHP 5)

fbsql_create_clob -- Crea un CLOB

Descrizione

string fbsql_create_clob ( string clob_data [, resource link_identifier] )

Restituisce un handle al CLOB appena creato.

La funzione fbsql_create_clob() crea un campo clob a partire da clob_data. L'handle restituito può essere utilizzato con i comandi di inserimento e di aggiornamento dei clob nel database.

Esempio 1. Esempio di uso di fbsql_create_clob()

<?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);
?>

Vedere anche: fbsql_create_blob(), fbsql_read_blob(), fbsql_read_clob() e fbsql_set_lob_mode().

fbsql_create_db

(PHP 4 >= 4.0.6, PHP 5)

fbsql_create_db -- Crea un database

Descrizione

bool fbsql_create_db ( string database name [, resource link_identifier] )

fbsql_create_db() crea un nuovo database FrontBase sul server, identificato dal parametro link_identifier.

Esempio 1. fbsql_create_db()

<?php
    $link = fbsql_pconnect ("localhost", "_SYSTEM", "secret")
        or die ("Could not connect");
    if (fbsql_create_db ("my_db")) {
        print("Database created successfully\n");
    } else {
        printf("Error creating database: %s\n", fbsql_error ());
    }
?>

Vedere anche fbsql_drop_db().

fbsql_data_seek

(PHP 4 >= 4.0.6, PHP 5)

fbsql_data_seek -- Sposta il puntatore del risultato interno

Descrizione

bool fbsql_data_seek ( resource result_identifier, int row_number )

Restituisce: TRUE in caso di successo, FALSE in caso di fallimento.

fbsql_data_seek() sposta il puntatore interno al risultato FrontBase associato con uno specificato indice in modo che punti ad un numero di riga specificata . La chiamata successiva alla funzionefbsql_fetch_row() restituirà la riga richiesta.

row_number comincia a contare da 0.

Esempio 1. fbsql_data_seek()

<?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;

        printf("%s %s<BR>\n", $row->last_name, $row->first_name);
    }

    fbsql_free_result ($result);
?>

fbsql_database_password

(PHP 4 >= 4.0.6, PHP 5)

fbsql_database_password -- Imposta o ricerca la password di un database FrontBase.

Descrizione

string fbsql_database_password ( resource link_identifier [, string database_password] )

Restituisce: La password del database identificato dal parametro link_identifier.

fbsql_database_password() imposta e ricerca la password del database corrente. Se il secondo parametro, opzionale (database_password), è stato specificato la funzione imposta, sul server, il valore del parametro come password del database identificato dal parametro link_identifier. Se il link_identifier non è specificato, verrà utilizzata l'ultima connessione aperta. Se nessuna connessione è aperta, la funzione tenterà di aprirne una come se la funzione fbsql_connect() fosse chiamata, e userà quella.

Questa funzione non modifica la password nel database e neppure è in grado ti recuperare la password di un database.

Esempio 1. Esempio di fbsql_create_clob()

<?php
    $link = fbsql_pconnect ("localhost", "_SYSTEM", "secret")
        or die ("Could not connect");
    fbsql_database_password($link, "secret db password");
    fbsql_select_db($database, $link);
?>

Vedere anche: fbsql_connect(), fbsql_pconnect() e fbsql_select_db().

fbsql_database

(PHP 4 >= 4.0.6, PHP 5)

fbsql_database -- Imposta oppure ottiene il nome del database usato per la connessione

Descrizione

string fbsql_database ( resource link_identifier [, string database] )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

fbsql_db_query

(PHP 4 >= 4.0.6, PHP 5)

fbsql_db_query -- Manda una query FrontBase

Descrizione

resource fbsql_db_query ( string database, string query [, resource link_identifier] )

Restituisce: un indice FrontBase positivo come risultato della query, o FALSE in caso di errore.

fbsql_db_query() seleziona un database ed esegue la query su di esso.Se il parametro opzionale link_identifier non è stato specificato, la funzione ne cercherà una già aperta nel FrontBase server, in caso non ne trovasse alcuna aprirà una nuova connessione come se la funzione fbsql_connect() fosse chiamta senza argomenti.

Vedere anche: fbsql_connect().

fbsql_db_status

(PHP 4 >= 4.1.0, PHP 5)

fbsql_db_status -- Restituisce lo stato di un dato database.

Descrizione

int fbsql_db_status ( string database_name [, resource link_identifier] )

Restituisce: un valore intero con lo stato corrente.

fbsql_db_status() richiede lo stato corrente del database specificato da database_name. Se il link_identifier viene omesso verrà usato quello in uso.

Il valore restituito potrà essere uno delle seguenti costanti:

FALSE - L'exec handler del host era invalido. Questo errore si presenta quando la connessione avviene direttamente al database, tramite il link_identifier, usando un numero di porta. FBExec può essere disponibile sul server ma nessuna connessione è stata creata.
FBSQL_UNKNOWN - Lo stato è sconosciuto.
FBSQL_STOPPED - Il database non è attivo. Usare fbsql_start_db() per attivare il database.
FBSQL_STARTING - Il database è in fase di attivazione.
FBSQL_RUNNING - Il database è attivo e può essere usato per eseguire operazioni SQL.
FBSQL_STOPPING - Il database é in fase di disattivazione.
FBSQL_NOEXEC - FBExec non è attivo sul server quindi non è possibile conoscere lo stato del database.

Vedere anche: fbsql_start_db() e fbsql_stop_db().

fbsql_drop_db

(PHP 4 >= 4.0.6, PHP 5)

fbsql_drop_db -- Cancella un database FrontBase

Descrizione

bool fbsql_drop_db ( string database_name [, resource link_identifier] )

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

fbsql_drop_db() procede con l'eliminazione di un intero database dal server associato all'identificatore di link.

fbsql_errno

(PHP 4 >= 4.0.6, PHP 5)

fbsql_errno -- Ritorna il valore numerico del messaggio di errore emesso dalla precedente operazione FrontBase.

Descrizione

int fbsql_errno ( [resource link_identifier] )

Restituisce il numero di errore dell'ultima funzione fbsql, 0 (zero) se non ci sono stati errori.

Gli errori vengono restituiti dal database fbsql senza visualizzare i warnings. Usare fbsql_errno() per ricevere codice dell'errore. Da notare che questa funzione restituisce solamente il codice di errore proveniente dalla più recente esecuzione di una funzione fbsql (escludendo fbsql_error() e fbsql_errno()),così se si vuole usarla, assicurarsi di controllare il valore prima di richiamare un'altra funzione fbsql.

<?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>";
?>

Vedere anche: fbsql_error() e fbsql_warnings().

fbsql_error

(PHP 4 >= 4.0.6, PHP 5)

fbsql_error -- Ritorna il testo del messaggio di errore emesso dalla precedente operazione FrontBase.

Descrizione

string fbsql_error ( [resource link_identifier] )

Restituisce il testo del messaggio di errore dell'ultima funzione fbsql, o '' (una stringa vuota) se non ci sono stati errori.

<?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>";
?>

Vedere anche: fbsql_errno() e fbsql_warnings().

fbsql_fetch_array

(PHP 4 >= 4.0.6, PHP 5)

fbsql_fetch_array -- Restituisce una riga (tupla) di risultato in forma di Array associativo, Array enumerato o entrambi

Descrizione

array fbsql_fetch_array ( resource result [, int result_type] )

Restituisce un array che corrisponde alla riga di risultato, o FALSE se non ci sono righe successive.

fbsql_fetch_array() è una versione estesa di fbsql_fetch_row(). In aggiunta all'inserimento dei dati negli elementi dell'array con indice numerico, li inserisce anche in indici associativi, usando il nome dei campi come chiavi.

Se due o più colonne di risultato hanno lo stesso nome di campo , l'ultima colonna sovrascriverà la precedente con lo stesso nome. Per accedere alle altre colonne con lo stesso nome si deve usare l'indice numerico oppure fare un alias della colonna.

select t1.f1 as foo t2.f1 as bar from t1, t2

Una cosa importante da notare è che fbsql_fetch_array() NON è singnificativamente più lenta di fbsql_fetch_row(), mentre fornisce un significativo valore aggiunto.

Il secondo parametro opzionale, result_type in fbsql_fetch_array() è una costante che può assumere i seguenti valori: FBSQL_ASSOC, FBSQL_NUM, and FBSQL_BOTH.

Per ulteriori dettagli vedere anche fbsql_fetch_row() e fbsql_fetch_assoc().

Esempio 1. fbsql_fetch_array()

<?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);
?>

fbsql_fetch_assoc

(PHP 4 >= 4.0.6, PHP 5)

fbsql_fetch_assoc -- Restituisce una riga (tupla) di risultato in forma di Array associativo.

Descrizione

array fbsql_fetch_assoc ( resource result )

Restituisce un array associativo corrispondente alla riga di risultato, o FALSE se non ci sono righe successive.

fbsql_fetch_assoc() è equivalente ad una chiamata a fbsql_fetch_array() con FBSQL_ASSOC come parametro opzionale. Restituirà solo un array associativo. fbsql_fetch_array() originariamente lavora in questo modo. Se si vuole un indice numerico come pure quello associativo, usare fbsql_fetch_array().

Se due o più colonne di risultato hanno lo stesso nome di campo , l'ultima colonna sovrascriverà la precedente con lo stesso nome. Per accedere alle altre colonne con lo stesso nome si deve usare fbsql_fetch_array() che ritorna un indice numerico.

Una cosa importante da notare è che fbsql_fetch_assoc() NON è singnificativamente più lenta di fbsql_fetch_row(), mentre fornisce un significativo valore aggiunto.

Per maggiori dettagli, vedi anche fbsql_fetch_row() e fbsql_fetch_array().

Esempio 1. fbsql_fetch_assoc()

<?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);
?>

fbsql_fetch_field

(PHP 4 >= 4.0.6, PHP 5)

fbsql_fetch_field -- Ottiene informazioni su una colonna da un set di risultati come oggetto

Descrizione

object fbsql_fetch_field ( resource result [, int field_offset] )

Restituisce un oggetto contenente le informazioni del campo.

La funzione fbsql_fetch_field() può essere utilizzata per ottenere informazioni sui campi da un set di risultati. Se non si specifica l'offset del campo, la funzione resituisce i le informazione sul campo successivo non ancora letto da fbsql_fetch_field().

Le proprietà dell'oggetto sono:

name - nome della colonna
table - nome della tabella da cui deriva la colonna
max_length - lunghezza massima della colonna
not_null - 1 se la colonna non può essere NULL
type - tipo di colonna

Esempio 1. Esempio di uso di fbsql_fetch_field()

<?php 
fbsql_connect($host, $user, $password)
    or die("Connessione non riuscita");
$result = fbsql_db_query("database", "select * from table")
    or die("Query fallita");
# ottiene i dati della colonna
$i = 0;
while ($i < fbsql_num_fields($result)) {
    echo "Informazioni per la colonna $i:<br />\n";
    $meta = fbsql_fetch_field($result);
    if (!$meta) {
        echo "Nessuna informazione disponibile<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);
?>

Vedere anche fbsql_field_seek().

fbsql_fetch_lengths

(PHP 4 >= 4.0.6, PHP 5)

fbsql_fetch_lengths -- Ottiene la lunghezza di ciascun output in un set di risultati

Descrizione

array fbsql_fetch_lengths ( [resource result] )

La funzione restituisce un array contenente le lunghezze di ciascun campo nell'ultima riga letta da fbsql_fetch_row(), oppure FALSE se si verifica un errore.

fbsql_fetch_lengths() memorizza le lunghezze di ciascuna colonna dall'ultima riga letta da fbsql_fetch_row(), da fbsql_fetch_array() e da fbsql_fetch_object() in un vettore, partendo dall'offset 0.

Vedere anche fbsql_fetch_row().

fbsql_fetch_object

(PHP 4 >= 4.0.6, PHP 5)

fbsql_fetch_object -- Resituisce un riga da un set di risultati come oggetto

Descrizione

object fbsql_fetch_object ( resource result [, int result_type] )

(PHP 4 >= 4.0.6, PHP 5)

fbsql_field_name -- Restituisce il nome del campo specificato

Descrizione

string fbsql_field_name ( resource result, int field_index )

La funzione fbsql_field_name() restituisce il nome del campo indicato da field_index. Il parametro result deve essere un valido identificatore di un set di risultati e field_index l'indice del campo.

Nota: field_index parte da 0.
Esempio: l'indice del terzo campo sarà 2, l'indice del quarto sarà 3 e così via.

Esempio 1. Esempio di uso di fbsql_field_name()
<?php // La tabella users è composta da tre campi: // 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); ?>
L'esempio precedente visualizzerà:
user_id password

fbsql_field_seek

(PHP 4 >= 4.0.6, PHP 5)

fbsql_field_seek -- Imposta il puntatore del set di risultati ad un specifico indice di campo

Descrizione

bool fbsql_field_seek ( resource result, int field_offset )

int fbsql_insert_id ( [resource link_identifier] )

La funzione fbsql_insert_id() restituisce l'ID generato per una colonna definita come DEFAULT UNIQUE da una precedente query INSERT eseguita sulla connessione link_identifier. Se non si specifica link_identifier si assume l'ultimo link aperto.

fbsql_insert_id()restituisce 0 ise la precedente query non ha generato campo impostati a DEFAULT UNIQUE. Se si desidera salvare il valore per usi futuri, occorre essere sicuri di eseguire fbsql_insert_id() immediatamente dopo la query che genera il valore.

Nota: Il valore restituito dalla funzione fbsql_insert_id() di FrontBase SQL contiene sempre il più recente valore DEFAULT UNIQUE prodotto, e non viene azzerato tra le query.

fbsql_list_dbs

(PHP 4 >= 4.0.6, PHP 5)

fbsql_list_dbs -- Elenca i database presenti su un server FrontBase

Descrizione

resource fbsql_list_dbs ( [resource link_identifier] )

La funzione fbsql_list_dbs() restituirà il puntatore ad un risultato contenente l'elenco dei databse disponibili dal corrente servizio fbsql. Utilizzare la funzione fbsql_tablename() per muoversi tra i risultati del puntatore

Esempio 1. Esempio di uso di fbsql_list_dbs()
$link = fbsql_connect('localhost', 'myname', 'secret'); $db_list = fbsql_list_dbs($link); while ($row = fbsql_fetch_object($db_list)) { echo $row->Database . "\n"; }
L'esempio precedente visualizzerà:
database1 database2 database3 ...

Nota: L'esempio precedente sarebbe semplice con fbsql_fetch_row() o altre funzioni simili.

fbsql_list_fields

(PHP 4 >= 4.0.6, PHP 5)

fbsql_list_fields -- Elenca i campi di un set di risultati

Descrizione

resource fbsql_list_fields ( string database_name, string table_name [, resource link_identifier] )

fbsql_list_fields() recupera informazioni sulla tabella data. I parametri passati sono il nome del database ed il nome della tabella. La funzione resituisce un puntatore alle infomrazioni che può essere utilizzato con fbsql_field_flags(), fbsql_field_len(), fbsql_field_name() e fbsql_field_type().

Il valore restituito è un intero positivo. La funzione restituisce FALSE se si verifica un errore. In caso di errore, nel campo $phperrmsg si avrà un testo con la descrizione dell'errore, e, a meno che la funzione non sia richiamata come @fbsql() questo testo sarà visualizzato.

Esempio 1. Esempio di uso di fbsql_list_fields()
<?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";; } ?>
L'esempio precedente visualizzerà:
field1 field2 field3 ...

fbsql_list_tables

(PHP 4 >= 4.0.6, PHP 5)

fbsql_list_tables -- Elenxa le tabelle presenti in un database FrontBase

Descrizione

resource fbsql_list_tables ( string database [, resource link_identifier] )

La funzione fbsql_list_tables() prende il nome del database e restituisce e restituisce un puntatore come la funzione fbsql_db_query(). A questo punto occorre utilizzare la funzione fbsql_tablename() per ottenere il nome delle tabelle dal puntatore ottenuto.

fbsql_next_result

(PHP 4 >= 4.0.6, PHP 5)

fbsql_next_result -- Muove il puntatore interno al risultato successivo

Descrizione

bool fbsql_next_result ( resource result_id )

Quando si invia più di un comando SQL al server o si esegue una 'stored procedure' che generi più risultati, si spinge il server a generare più set di risultati. Questa funzione verifica la disponibilità di set aggiuntivi dal server. Se esiste un set di risultati aggiuntivo, la funzione libererà la memoria del set corrente e si prepare a scaricare il nuovo. La funzione restituisce TRUE se è disponibile un nuovo set di risultati, oppure FALSE se non ve ne sono.

Esempio 1. Esempio di uso di fbsql_next_result()

<?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);
?>

Per impostare il numero di porta del server FrontBase utilzzare fbsql_select_db().

fbsql_pconnect() agisce in modo simile a fbsql_connect() con due differenze.

Primo, durante la connessione la funzione prima tenta di trovare una connessione (persistente) per il medesimo server già aperta, con il medesimo utente e la medesima password. Se si trova una connessione verrà restituito l'identificatore di questa piuttosto che aprire una nuova connessione.

Secondo, la connessione al server SQL non verrà chiusa al termine dello script. Resterà, invece. aperta per usi futuri.

Questo tipo di connessione è, quindi, chiamata 'persistente'.

fbsql_query

(PHP 4 >= 4.0.6, PHP 5)

fbsql_query -- Invia una query a FrontBase

Descrizione

resource fbsql_query ( string query [, resource link_identifier] )

La funzione fbsql_query() invia una query al database al database attivo sul collegamento identificato da link_identifier. Se non si specifica link_identifier, si utilizzerà l'ultimo collegamento aperto. Se non vi sono collegamenti attivi la funzione tenta di stabilirne uno come se si chiamasse fbsql_connect() senza parametri.

Nota: Il testo della query deve terminare sempre con punto e virgola.

La funzione fbsql_query() restituisce TRUE (non-zero) oppure FALSE per indicare se la query ha avuto successo o meno. Un valore di ritorno pari a TRUE indica che la query è valida e può essere eseguita dal server. Il valore di ritorno non indica nulla su quante sono le righe coinvolte. Pertanto è possibile che una query abbia successo, ma non coinvolga alcuna riga.

mixed fbsql_result ( resource result, int row [, mixed field] )

La funzione fbsql_result() restituisce il contenuto di una cella da un set di risultati di una query a FrontBase. L'argomento field può essere l'offset del campo, o il nome del campo, oppure nome della tabella del campo punto nome del campo (nometabella.nomecampo). Se il nome della colonna ha un alias ('select foo as bar from...'), usare l'alias al posto del nome della colonna.

Quando si lavora con grandi set di risultati, si può considerare l'utilizzo delle funzioni che restituiscono l'intera riga (elencate di seguito). Poichè queste restituiscono il contenuto di più celle con una singola chiamata, esse sono MOLTO più veloci che fbsql_result(). Occorre far notare, inoltre, che specificando l'offset numerico del campo si ottiene un'esecuzione più veloce rispetto alla specifica del nome del campo o di nometabella.nomecampo.

Le chiamate a fbsql_result() non dovrebbero essere mischiate con con chiamate ad altre funzioni che agiscano sul set di risultati.

Alternative più performanti raccomandate: fbsql_fetch_row(), fbsql_fetch_array() e fbsql_fetch_object().

fbsql_rollback

(PHP 4 >= 4.0.6, PHP 5)

fbsql_rollback -- Esegue il rollback della transazione

Descrizione

bool fbsql_rollback ( [resource link_identifier] )

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

La funzione fbsql_rollback() termina la transazione corrente eseguendo il rollback di tutte le istruzioni dall'ultimo commit. Questo comando è necessario solo se autocommit è impostato a false.

Vedere anche: fbsql_autocommit() e fbsql_commit()

fbsql_select_db

(PHP 4 >= 4.0.6, PHP 5)

fbsql_select_db -- Seleziona un database FrontBase

Descrizione

bool fbsql_select_db ( string database_name [, resource link_identifier] )

La funzione fbsql_select_db() attiva il database corrente sul server associato alla connessione specificata da link_identifier Se non si passa link_identifier, si considera l'ultima connessione aperta. Se non vi sono connessioni aperte, la funzione tenta di stabilirne una come se fosse eseguita la funzione fbsql_connect().

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Il client contatta FBExec per ottenere il numero diporta per stabilire la connessione al database. Se database_name è un numero il sistema userà quel numero come porta e non chiederà un numero di porta a FBExec. Il server FrontBase può essere avviato come FRontBase -FBExec=No -port=<port number> <database name>.

Ogni chiamata successiva a fbsql_query() sarà eseguita sul database attivo.

Se il database è protetto con una password, l'utente deve eseguire fbsql_database_password() prima di selezionare il database.

Vedere anche: fbsql_connect(), fbsql_pconnect(), fbsql_database_password() e fbsql_query().

fbsql_set_lob_mode

(PHP 4 >= 4.2.0, PHP 5)

fbsql_set_lob_mode -- Imposta la modalità LOB in un set di risultati FrontBase

Descrizione

bool fbsql_set_lob_mode ( resource result, string database_name )

Restituisce: TRUE se ha successo, FALSE se si verifica un errore.

La funzione fbsql_set_lob_mode() la modalità per il recupero dei dati LOB dal database. Quando i dati BLOB e CLOB sono memorizzati in FrontBase questi possono essere memorizzati direttamente o indirettamente. I dati LOB archiviati direttamente sono sempre recuperati a prescindere dell'impostazione della modalità LOB. Se i dati LOB sono meno di 512 byte saranno sempre archiviati direttamente.

FBSQL_LOB_DIRECT - I dati LOB sono recuperati direttamente. Quando i dati sono ottenuti dal database con fbsql_fetch_row(), o altre funzioni per il recupero dei dati, tutte le colonne BLOB saranno restituite come colonne ordinarie. Questo è il valore di default in un nuovo set di risultati.
FBSQL_LOB_HANDLE - I dati LOB sono recuperati come puntatori ai dati. Quando si recupera le informazioni da un database con fbsql_fetch_row (), o altre funzioni per il recupero dei dati, i dati LOB saranno restituiti come handle ai dati, se questi sono stati memorizzati indirettamente o saranno restituiti direttamente i dati se questi sono memorizzati in modo diretto. Se la funzione restituisce un handle, questo sarà una stringa di 27 byte con il formato tipo "@'000000000000000000000000'".

fbsql_start_db()

Vedere anche: fbsql_db_status() e fbsql_stop_db().

fbsql_stop_db

(PHP 4 >= 4.0.6, PHP 5)

fbsql_stop_db -- Ferma un database locale o remoto

Descrizione

bool fbsql_stop_db ( string database_name [, resource link_identifier] )

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

fbsql_stop_db()

Vedere anche: fbsql_db_status() e fbsql_start_db().

fbsql_tablename

(PHP 4 >= 4.2.0, PHP 5)

fbsql_tablename -- Restituisce il nome della tabella dei campi

Descrizione

string fbsql_tablename ( resource result, int i )

La funzione fbsql_tablename() utilizza il puntatore al risultato restituito da fbsql_list_tables() e restituisce il nome della tabella. Si può, inoltre, utilizzare la funzione fbsql_num_rows() per determinare il numero di tabelle presenti in un risultato.
Esempio 1. Esempio di uso di fbsql_tablename()
<?php fbsql_connect("localhost", "_SYSTEM", ""); $result = fbsql_list_tables("wisconsin"); $i = 0; while ($i < fbsql_num_rows($result)) { $tb_names[$i] = fbsql_tablename($result, $i); echo $tb_names[$i] . "<br />"; $i++; } ?>

fbsql_username

(PHP 4 >= 4.0.6, PHP 5)

fbsql_username -- Ottiene o imposta l'utente per la connessione

Descrizione

string fbsql_username ( resource link_identifier [, string username] )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

fbsql_warnings

(PHP 4 >= 4.0.6, PHP 5)

fbsql_warnings -- Abilita o disabilita i warnings FrontBase

Descrizione

bool fbsql_warnings ( [bool OnOff] )

Restituisce TRUE se i warnings sono abilitati oppure FALSE.

La funzione fbsql_warnings() abilita o disabilita i warnings FrontBase.

XLIII. Funzioni FTP

Le funzioni in questa estensione implementano l'accesso client ad un file server utilizzando il File Transfer Protocol (FTP) come definito in http://www.faqs.org/rfcs/rfc959.html.

Usando il modulo FTP vengono definite le seguenti costanti: FTP_ASCII e FTP_BINARY.

Per l'utilizzo delle funzioni FTP con la vostra configurazione PHP, dovrete aggiungere l'opzione --enable-ftp durante l'installazione PHP 4, e --with-ftp nell'installazione di PHP 3.

Esempio 1. FTP
<?php // stabilire una connessione $conn_id = ftp_connect($ftp_server); // login con user name e password $login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass); // controllo della connessione if ((!$conn_id) || (!$login_result)) { echo "La connessione FTP è fallita!"; echo "Tentativo di connessione a $ftp_server per l'utente $ftp_user_name"; die; } else { echo "Connesso a $ftp_server, utente $ftp_user_name"; } // upload del file $upload = ftp_put($conn_id, $destination_file, $source_file, FTP_BINARY); // controllo dello stato di upload if (!$upload) { echo "Il caricamento FTP non è andato a buon fine!"; } else { echo "Caricato il file $source_file su $ftp_server come $destination_file"; } // chiudere il flusso FTP ftp_quit($conn_id); ?>

Sommario
ftp_alloc -- Allocates space for a file to be uploaded
ftp_cdup -- Passa alla directory superiore
ftp_chdir -- Cambia le directory su un server FTP
ftp_chmod -- Set permissions on a file via FTP
ftp_close -- Chiude una connessione FTP
ftp_connect -- Apre una connessione FTP
ftp_delete -- Cancella un file sul server FTP
ftp_exec -- Richiede l'esecuzione di un programma sul server FTP
ftp_fget -- Scarica un file dal server FTP e lo salva su un file aperto
ftp_fput -- Carica un file aperto sul server FTP
ftp_get_option -- Recupera diversi comportamenti dello stream FTP durante l'esecuzione
ftp_get -- Scarica un file dal server FTP
ftp_login -- Esegue il log ad una connessione FTP
ftp_mdtm -- Restituisce l'orario dell'ultima modifica al file corrente
ftp_mkdir -- Crea una directory
ftp_nb_continue -- Continua a ricevere/trasmettere un file in modalita' non bloccante
ftp_nb_fget -- Recupera un file dal server FTP e lo scrive su un file aperto, in modalita' non bloccante
ftp_nb_fput -- Salva il contenuto di un file aperto sul server FTP in modalita' non bloccante
ftp_nb_get -- Recupera un file dal server FTP e lo scrive su un file locale in modalita' non bloccante
ftp_nb_put -- Salva un file sul server FTP in modalita' non bloccante
ftp_nlist -- Restituisce la lista dei file nella directory prescelta
ftp_pasv -- Attivaa o disattiva il modo passivo
ftp_put -- Trasferisce un file al server FTP
ftp_pwd -- Restituisce il nome della directory corrente
ftp_quit -- Alias di ftp_close()
ftp_raw -- Invia un comando di qualsiasi tipo ad un server FTP
ftp_rawlist -- Restituisce un elenco dettagliato dei files nella directory in esame
ftp_rename -- Rinomina un file sul server FTP
ftp_rmdir -- Elimina una directory
ftp_set_option -- Imposta varie opzioni per l'esecuzione di FTP
ftp_site -- Invia al server un comando SITE
ftp_size -- Restituisce le dimensioni del file specificato
ftp_ssl_connect -- Apre una connessione SSL-FTP connessione
ftp_systype -- Restituisce l'identificatore di tipo del server FTP remoto

ftp_alloc

(PHP 5)

ftp_alloc -- Allocates space for a file to be uploaded

Descrizione

bool ftp_alloc ( resource ftp_stream, int filesize [, string &result] )

Sends an ALLO command to the remote FTP server to allocate space for a file to be uploaded.

Nota: Many FTP servers do not support this command. These servers may return a failure code (FALSE) indicating the command is not supported or a success code (TRUE) to indicate that pre-allocation is not necessary and the client should continue as though the operation were successful. Because of this, it may be best to reserve this function for servers which explicitly require preallocation.

Elenco dei parametri

ftp_stream: The link identifier of the FTP connection.
filezise: The number of bytes to allocate.
return: A textual representation of the servers response will be returned by reference in result if a variable is provided.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 1. ftp_alloc() example
<?php $file = "/home/user/myfile"; /* connect to the server */ $conn_id = ftp_connect('ftp.example.com'); $login_result = ftp_login($conn_id, 'anonymous', 'user@example.com'); if (ftp_alloc($conn_id, filesize($file), $result)) { echo "Space successfully allocated on server. Sending $file.\n"; ftp_put($conn_id, '/incomming/myfile', $file, FTP_BINARY); } else { echo "Unable to allocate space on server. Server said: $result\n"; } ftp_close($conn_id); ?>

Vedere anche:

ftp_put()

ftp_fput()

ftp_cdup

(PHP 3 >= 3.0.13, PHP 4, PHP 5)

ftp_cdup -- Passa alla directory superiore

Descrizione

bool ftp_cdup ( resource ftp_stream )

Passa alla directory superiore.

Esempio 1. ftp_cdup() example
<?php // stabilisce la connessione $conn_id = ftp_connect($ftp_server); // si collega con nome utente e password $login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass); // cambia la directory corrente in html ftp_chdir($conn_id, 'html'); echo ftp_pwd($conn_id); // /html // torna alla directory padre if (ftp_cdup($conn_id)) { echo "cdup successful\n"; } else { echo "cdup not successful\n"; } echo ftp_pwd($conn_id); // / ftp_close($conn_id); ?>

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedi anche ftp_chdir().

ftp_chdir

(PHP 3 >= 3.0.13, PHP 4, PHP 5)

ftp_chdir -- Cambia le directory su un server FTP

Descrizione

bool ftp_chdir ( resource ftp_stream, string directory )

Passa dalla directory corrente alla directory specificata.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempio 1. esempio ftp_chdir()

<?php

// stabilisce la connessione
$conn_id = ftp_connect($ftp_server); 

// si collega con nome utente e password
$login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass); 

// controlla la connessione
if ((!$conn_id) || (!$login_result)) {
    die("FTP connection has failed !");
}

echo "Current directory: " . ftp_pwd($conn_id) . "\n";

// tenta di passare alla directory somedir
if (ftp_chdir($conn_id, "somedir")) {
    echo "Current directory is now: " . ftp_pwd($conn_id) . "\n";
} else { 
    echo "Couldn't change directory\n";
}

// chiude la connessione
ftp_close($conn_id);
?>

Vedi anche ftp_cdup().

ftp_chmod

(PHP 5)

ftp_chmod -- Set permissions on a file via FTP

Descrizione

int ftp_chmod ( resource ftp_stream, int mode, string filename )

Sets the permissions on the specified remote file to mode.

Elenco dei parametri

ftp_stream: The link identifier of the FTP connection.
mode: The new permissions, given as an octal value.
filename: The remote file.

Valori restituiti

Returns the new file permissions on success or FALSE on error.

Esempi

Esempio 1. ftp_chmod() example
<?php $file = 'public_html/index.php'; // set up basic connection $conn_id = ftp_connect($ftp_server); // login with username and password $login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass); // try to chmod $file to 644 if (ftp_chmod($conn_id, 0644, $file) !== false) { echo "$file chmoded successfully to 644\n"; } else { echo "could not chmod $file\n"; } // close the connection ftp_close($conn_id); ?>

Vedere anche:

chmod()

ftp_close

(PHP 4 >= 4.2.0, PHP 5)

ftp_close -- Chiude una connessione FTP

Descrizione

void ftp_close ( resource ftp_stream )

ftp_close() chiude ftp_stream e rilascia la risorsa. Dopo aver chiamato questa funzione, non e' piu' possibile usare la connessione FTP ed e' necessario crearne una nuova con ftp_connect().

Esempio 1. esempio di funzione ftp_close()
<?php //stabilisce la connessione $conn_id = ftp_connect($ftp_server); // si collega con nome utente e password $login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass); // stampa la directory corrente echo ftp_pwd($conn_id); // / // chiude la connessione ftp_close($conn_id); ?>

Vedere anche ftp_connect()

ftp_connect

(PHP 3 >= 3.0.13, PHP 4, PHP 5)

ftp_connect -- Apre una connessione FTP

Descrizione

resource ftp_connect ( string host [, int port [, int timeout]] )

Restituisce un flusso FTP stream in caso di successo, FALSE in caso di errore.

La funzione ftp_connect() apre una connessione FTP all' host specificato. host non deve essere seguito da barre e non deve essere precedeuto da ftp://. Il parametro port specifica una porta alternativa cui connettersi. Se e' omesso o impostato a zero verra' usata la porta 21, default di FTP.

Il parametro timeout specifica il timeout per tutte le successive operazioni di rete. Se omesso il valore predefinito e' di 90 secondi. Il timeout puo' essere modificato o interrogato in qualsiasi momento con ftp_set_option() e ftp_get_option().

Nota: Il parametro timeout e' disponibile a partire dalla release PHP 4.2.0.

Esempio 1. Esempio di funzione ftp_connect()

<?php

$ftp_server = "ftp.example.com";

// stabilisce una connessione o esce
$conn_id = ftp_connect($ftp_server) or die("Impossibile collegarsi a $ftp_server"); 

?>

Nota: Il parametro resumepos e' stato aggiunto in PHP 4.3.0.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche ftp_get(), ftp_nb_get() e ftp_nb_fget().

ftp_fput

(PHP 3 >= 3.0.13, PHP 4, PHP 5)

ftp_fput -- Carica un file aperto sul server FTP

Descrizione

bool ftp_fput ( resource ftp_stream, string remote_file, resource handle, int mode [, int startpos] )

ftp_fput() carica i dati del file cui fa riferimento il puntatore handle fino a quando viene raggiunta la fine del file. I risultati sono salvati in remote_file sul server FTP. Il modo di trasferimento mode specificato deve essere FTP_ASCII oppure FTP_BINARY.

Esempio 1. Esempio di funzione ftp_fput()
<?php // apre in lettura un qualche file $file = 'somefile.txt'; $fp = fopen($file, 'r'); // stabilisce la connessione $conn_id = ftp_connect($ftp_server); // si collega con nome utente e password $login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass); // prova a caricare $file if (ftp_fput($conn_id, $file, $fp, FTP_ASCII)) { echo "$file caricato con successo\n"; } else { echo "Problemi con il caricamento di $file\n"; } // chiude la connessione e l'handle del file ftp_close($conn_id); fclose($fp); ?>

Nota: Il parametro startpos e' stato aggiunto in PHP 4.3.0.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche ftp_put(), ftp_nb_fput(), e ftp_nb_put().

ftp_get_option

(PHP 4 >= 4.2.0, PHP 5)

ftp_get_option -- Recupera diversi comportamenti dello stream FTP durante l'esecuzione

Descrizione

mixed ftp_get_option ( resource ftp_stream, int option )

Restituisce il valore in caso di successo oppure FALSE se l'opzione option data non e' supportata. In quest'ultimo caso, viene anche visualizzato un messaggio di avvertimento.

Questa funzione restituisce il valore dell'opzione option richiesta dallo stream FTP ftp_stream specificato. Attualmente sono riconosciute le seguenti opzioni:

Tabella 1. Opzioni di runtime FTP riconosciute

FTP_TIMEOUT_SEC

Restituisce il timeout corrente, usato in operazioni di rete.

Esempio 1. Esempio di funzione ftp_get_option()

<?php
// Recupera il time out dello stream FTP richiesto
$timeout = ftp_get_option($conn_id, FTP_TIMEOUT_SEC);
?>

Vedere anche ftp_set_option().

ftp_get

(PHP 3 >= 3.0.13, PHP 4, PHP 5)

ftp_get -- Scarica un file dal server FTP

Descrizione

bool ftp_get ( resource ftp_stream, string local_file, string remote_file, int mode [, int resumepos] )

ftp_get() recupera remote_file dal server FTP, e lo salva sul file locale local_file. Il modo di trasferimento mode specificato deve essere FTP_ASCII oppure FTP_BINARY.

Nota: Il parametro resumepos e' stato aggiunto in PHP 4.3.0.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempio 1. Esempio di funzione ftp_get()
<?php // definisce alcune variabili $local_file = 'local.zip'; $server_file = 'server.zip'; // stabilisce la connessione $conn_id = ftp_connect($ftp_server); // si collega con nome utente e password $login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass); // prova a scaricare $server_file e a salvarlo su $local_file if (ftp_get($conn_id, $local_file, $server_file, FTP_BINARY)) { echo "Scrittura su $local_file terminata con successo\n"; } else { echo "Problemi nello scaricamento\n"; } // chiude la connessione ftp_close($conn_id); ?>

Vedere anche ftp_fget(), ftp_nb_get() e ftp_nb_fget().

ftp_login

(PHP 3 >= 3.0.13, PHP 4, PHP 5)

ftp_login -- Esegue il log ad una connessione FTP

Descrizione

bool ftp_login ( resource ftp_stream, string username, string password )

Esegue il log allo stream FTP richiesto.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempio 1. Esempio di funzione ftp_login()

<?php
                     
$ftp_server = "ftp.example.com";
$ftp_user = "foo";
$ftp_pass = "bar";

// esegue una connessione o esce
$conn_id = ftp_connect($ftp_server) or die("Impossibile connettersi a $ftp_server"); 

// prova a connettersi
if (@ftp_login($conn_id, $ftp_user, $ftp_pass)) {
    echo "Connesso come $ftp_user@$ftp_server\n";
} else {
    echo "Impossibile connettersi come $ftp_user\n";
}

// chiude la connessione
ftp_close($conn_id);  
?>

ftp_mdtm

(PHP 3 >= 3.0.13, PHP 4, PHP 5)

ftp_mdtm -- Restituisce l'orario dell'ultima modifica al file corrente

Descrizione

int ftp_mdtm ( resource ftp_stream, string remote_file )

La funzione ftp_mdtm() controlla l'orario dell'ultima modifica ad un file, e lo restituisce in formato timestamp Unix. Se si verifica un errore, o il file non esiste, restituisce -1.

Restituisce un timestamp Unix in caso di successo, o -1 in caso di errore.

Esempio 1. Esempio di funzione ftp_mdtm()
<?php $file = 'somefile.txt'; // stabilisce la connessione $conn_id = ftp_connect($ftp_server); // si collega con nome utente e password $login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass); // recupera l'ultimo orario di modifica $buff = ftp_mdtm($conn_id, $file); if ($buff != -1) { // somefile.txt e' stato modificato l'ultima volta il: 26 marzo 2003 14:16:41. echo "$file e' stato modificato l'ultima volta il : " . date("F d Y H:i:s.", $buff); } else { echo "Impossibile visualizzare mdtime"; } // chiude la connessione ftp_close($conn_id); ?>

Nota: Non tutti i server includono questa funzione!

Nota: La funzione ftp_mdtm() non funziona con le directories.

ftp_mkdir

(PHP 3 >= 3.0.13, PHP 4, PHP 5)

ftp_mkdir -- Crea una directory

Descrizione

string ftp_mkdir ( resource ftp_stream, string directory )

Crea la directory specificata sul server FTP.

Restituisce la directory appena creata in caso di successo o FALSE in caso di errore.

Esempio 1. Esempio di funzione ftp_mkdir()
<?php $dir = 'www'; // stabilisce la connessione $conn_id = ftp_connect($ftp_server); // si collega con nome utente e password $login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass); // prova a creare la directory $dir if (ftp_mkdir($conn_id, $dir)) { echo "$dir creata con successo\n"; } else { echo "Problemi nella creazione di $dir\n"; } // chiude la connessione ftp_close($conn_id); ?>

Vedere anche ftp_rmdir().

ftp_nb_continue

(PHP 4 >= 4.3.0, PHP 5)

ftp_nb_continue -- Continua a ricevere/trasmettere un file in modalita' non bloccante

int ftp_nb_get ( resource ftp_stream, string local_file, string remote_file, int mode [, int resumepos] )

La funzione ftp_nb_get() recupera remote_file dal server FTP, e lo salva localmente su local_file. La modalita' di trasferimento, mode, specificata deve essere FTP_ASCII oppure FTP_BINARY. La differenza tra questa funzione e la funzione ftp_get() e' che questa funzione recupera il file in modo asincrono, cosicche' il programma puo' eseguire altre operazioni mentre il file viene scaricato.

Restituisce FTP_FAILED, FTP_FINISHED, oppure FTP_MOREDATA.

Esempio 1. Esempio di funzione ftp_nb_get()
<?php // Inizia lo scaricamento $ret = ftp_nb_get($my_connection, "test", "README", FTP_BINARY); while ($ret == FTP_MOREDATA) { // esegue altre operazioni echo "."; // Continua lo scaricamento... $ret = ftp_nb_continue($my_connection); } if ($ret != FTP_FINISHED) { echo "Errore nello scaricamento del file..."; exit(1); } ?>

Esempio 2. Ripresa di uno scaricamento con ftp_nb_get()
<?php // Inizio $ret = ftp_nb_get($my_connection, "test", "README", FTP_BINARY, filesize("test")); // oppure: $ret = ftp_nb_get($my_connection, "test", "README", // FTP_BINARY, FTP_AUTORESUME); while ($ret == FTP_MOREDATA) { // esegue altre operazioni echo "."; // Continua lo scaricamento... $ret = ftp_nb_continue($my_connection); } if ($ret != FTP_FINISHED) { echo "Errore nello scaricamento del file..."; exit(1); } ?>

Esempio 3. Ripresa di uno scaricamento dalla posizione 100 su un nuovo file con ftp_nb_get()
<?php // Esclusione di Autoseek (ricerca automatica) ftp_set_option($my_connection, FTP_AUTOSEEK, false); // Inizio $ret = ftp_nb_get($my_connection, "newfile", "README", FTP_BINARY, 100); while ($ret == FTP_MOREDATA) { /* ... */ // Continua lo scaricamento... $ret = ftp_nb_continue($my_connection); } ?>

Nell'esempio precedente, "newfile" e' 100 bytes piu' piccolo di "README" sul server FTP perche' la lettura e' iniziata dall'offset 100. Se FTP_AUTOSEEKnon fosse stata disabilitata, i primi 100 bytes di "newfile" sarebbero stati '\0'.

Vedere anche ftp_nb_fget(), ftp_nb_continue(), ftp_get(), e ftp_fget().

ftp_nb_put

(PHP 4 >= 4.3.0, PHP 5)

ftp_nb_put -- Salva un file sul server FTP in modalita' non bloccante

Descrizione

int ftp_nb_put ( resource ftp_stream, string remote_file, string local_file, int mode [, int startpos] )

La funzione ftp_nb_put() salva local_file sul server FTP come remote_file. La modalita' di trasferimento, mode specificata deve essere FTP_ASCII oppure FTP_BINARY. La differenza tra questa funzione e la funzione ftp_put() e' che questa funzione trasferisce il file in modo asincrono, cosicche' il programma puo' eseguire altre operazioni durante il trasferimento.

Restituisce FTP_FAILED, FTP_FINISHED, oppure FTP_MOREDATA.

Esempio 1. Esempio di funzione ftp_nb_put()
<?php // Inizia il trasferimento $ret = ftp_nb_put($my_connection, "test.remote", "test.local", FTP_BINARY); while ($ret == FTP_MOREDATA) { // esegue altre operazioni echo "."; // continua il trasferimento... $ret = ftp_nb_continue($my_connection); } if ($ret != FTP_FINISHED) { echo "Errore nel trasferimento del file..."; exit(1); } ?>

Esempio 2. Ripresa di un trasferimento con ftp_nb_put()
<?php // Inizio $ret = ftp_nb_put($my_connection, "test.remote", "test.local", FTP_BINARY, ftp_size("test.remote")); // oppure: $ret = ftp_nb_put($my_connection, "test.remote", "test.local", // FTP_BINARY, FTP_AUTORESUME); while ($ret == FTP_MOREDATA) { // esegue altre operazioni echo "."; // Continua il trasferimento... $ret = ftp_nb_continue($my_connection); } if ($ret != FTP_FINISHED) { echo "Errore nel trasferimento del file..."; exit(1); } ?>

Vedere anche ftp_nb_fput(), ftp_nb_continue(), ftp_put(), e ftp_fput().

ftp_nlist

(PHP 3 >= 3.0.13, PHP 4, PHP 5)

ftp_nlist -- Restituisce la lista dei file nella directory prescelta

Descrizione

array ftp_nlist ( resource ftp_stream, string directory )

Restituisce un array di nomi di file dalla directory specificata in caso di corretta esecuzione oppure FALSE in caso di errore.

Esempio 1. Esempio di funzione ftp_nlist()

<?php

// stabilisce la connessione
$conn_id = ftp_connect($ftp_server);

// si collega con nome utente e password
$login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass);

// recupera il contenuto della directory corrente
$contents = ftp_nlist($conn_id, ".");

// visualizza $contents
var_dump($contents);

?>

L'esempio precedente visualizza qualcosa del tipo:

array(3) {
  [0]=>
  string(11) "public_html"
  [1]=>
  string(10) "public_ftp"
  [2]=>
  string(3) "www"

Vedere anche ftp_rawlist().

ftp_pasv

(PHP 3 >= 3.0.13, PHP 4, PHP 5)

ftp_pasv -- Attivaa o disattiva il modo passivo

Descrizione

bool ftp_pasv ( resource ftp_stream, bool pasv )

ftp_pasv() attiva il modo passivo se il parametro pasv e' TRUE. Disattiva il modo passivo se pasv e' FALSE. Nel modo passivo, le connessioni sono iniziate dal client piuttosto che dal server.

Esempio 1. Esempio di funzione ftp_pasv()
<?php $file = 'somefile.txt'; $remote_file = 'readme.txt'; // stabilisce la connessione $conn_id = ftp_connect($ftp_server); // si collega con username and password $login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass); // attiva il modo passivo ftp_pasv($conn_id, true); // trasferisce un file al server if (ftp_put($conn_id, $remote_file, $file, FTP_ASCII)) { echo "$file trasferito correttamente\n"; } else { echo "Si e' verificato un problema durante il trasferimento di $file\n"; } // chiude la connessione ftp_close($conn_id); ?>

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

ftp_put

(PHP 3 >= 3.0.13, PHP 4, PHP 5)

ftp_put -- Trasferisce un file al server FTP

Descrizione

bool ftp_put ( resource ftp_stream, string remote_file, string local_file, int mode [, int startpos] )

ftp_put() salva local_file sul server FTP come remote_file. Il modo di trasferimento mode specificato deve essere FTP_ASCII oppure FTP_BINARY.

Nota: Il parametro startpos e' stato aggiunto nella release PHP 4.3.0.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempio 1. Esempio di funzione ftp_put()
<?php $file = 'somefile.txt'; $remote_file = 'readme.txt'; // stabilisce la connessione $conn_id = ftp_connect($ftp_server); // si collega con username and password $login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass); // trasferisce un file al server if (ftp_put($conn_id, $remote_file, $file, FTP_ASCII)) { echo "$file trasferito correttamente\n"; } else { echo "Si e' verificato un problema durante il trasferimento di $file\n"; } // chiude la connessione ftp_close($conn_id); ?>

Vedere anche ftp_fput(), ftp_nb_fput(), e ftp_nb_put().

ftp_pwd

(PHP 3 >= 3.0.13, PHP 4, PHP 5)

ftp_pwd -- Restituisce il nome della directory corrente

Descrizione

string ftp_pwd ( resource ftp_stream )

(PHP 3 >= 3.0.13, PHP 4, PHP 5)

ftp_rmdir -- Elimina una directory

Descrizione

bool ftp_rmdir ( resource ftp_stream, string directory )

Elimina la directory specificata. directory deve essere un percorso assoluto o relativo ad una directory vuota.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempio 1. Esempio di funzione ftp_rmdir()
<?php $dir = 'www/'; // stabilisce la connesione $conn_id = ftp_connect($ftp_server); // si collega con username and password $login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass); // prova a eliminare la directory $dir if (ftp_rmdir($conn_id, $dir)) { echo "Directory $dir eliminata\n"; } else { echo "Si e' verificato un problema durante l'eliminazione di $dir\n"; } ftp_close($conn_id); ?>

Vedere anche ftp_mkdir().

ftp_set_option

(PHP 4 >= 4.2.0, PHP 5)

ftp_set_option -- Imposta varie opzioni per l'esecuzione di FTP

Descrizione

bool ftp_set_option ( resource ftp_stream, int option, mixed value )

Restituisce TRUE se e'stato possibile impostare l'opzione; FALSE altrimenti. Se l'opzione option non e' supportata o il valore value del parametro passato alla funzione non corrisponde al valore atteso per l'opzione option scelta, viene generato un messaggio di errore.

Questa funzione controlla varie opzioni che hanno effetto durante l'esecuzione dello stream FTP specificato. Il parametro value dipende da quale parametro option viene scelto per essere modificato. Attualmente sono riconosciute le seguenti opzioni:

Tabella 1. Opzioni supportate per l'esecuzione di FTP

FTP_TIMEOUT_SEC	Modifica il timeout in secondi utilizzata per tutte le funzioni di rete. Il parametro `value` deve essere un intero maggiore di 0. Il timeout predefinito e' di 90 secondi.
FTP_AUTOSEEK	Quando attivata, richieste GET or PUT con un parametro `resumepos` o `startpos` iniziano la ricerca dalla posizione richiesta all'interno del file. This is enabled Questa opzione e' attivata di default.

Il parametro timeout specifica il timeout per tutte le operazioni di rete successive. Se omesso il valore predefinito e' di 90 secondi. Il timeout puo' essere interrogato o modificato in qualsiasi momento con le funzioni ftp_set_option() e ftp_get_option().

Esempio 1. Esempio di funzione ftp_ssl_connect()
<?php // stabilisce una connessione ssl $conn_id = ftp_ssl_connect($ftp_server); // si collega come username e password $login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass); echo ftp_pwd($conn_id); // / // chiude la connessione ssl ftp_close($conn_id); ?>

Perche' questa funzione puo' non essere presente: La funzione ftp_ssl_connect() e' disponibile solo se il supporto OpenSSL e' abilitato nella versione corrente di PHP. Se non e' definito ed e' stato incluso il supporto a FTP durante la compilazione, questa e' la ragione per cui la funzione non e' presente.

Vedere anche ftp_connect().

ftp_systype

(PHP 3 >= 3.0.13, PHP 4, PHP 5)

ftp_systype -- Restituisce l'identificatore di tipo del server FTP remoto

Descrizione

string ftp_systype ( resource ftp_stream )

Restituisce il tipo del sistema remoto, o FALSE in caso di errore.

Esempio 1. Esempio di funzioneftp_systype()
<?php // connessione ftp $ftp = ftp_connect('ftp.example.com'); ftp_login($ftp, 'user', 'password'); // recupera il tipo del sistema if ($type = ftp_systype($ftp)) { echo "Example.com utilizza $type\n"; } else { echo "Impossibile determinare il tipo del sistema"; } ?>
L'esempio precedente produrra' in uscita qualosa di simile a:
Example.com utilizza UNIX

XLIV. Function Handling Functions

Introduzione

These functions all handle various operations involved in working with functions.

Requisiti

Non sono necessarie librerie esterne per utilizzare questo modulo.

Installazione

Non è necessaria nessuna installazione per usare queste funzioni, esse fanno parte del core di PHP.

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Costanti predefinite

Questa estensione non definisce alcuna costante.

Sommario
call_user_func_array -- Call a user function given with an array of parameters
call_user_func -- Call a user function given by the first parameter
create_function -- Create an anonymous (lambda-style) function
func_get_arg -- Return an item from the argument list
func_get_args -- Returns an array comprising a function's argument list
func_num_args -- Returns the number of arguments passed to the function
function_exists -- Return TRUE if the given function has been defined
get_defined_functions -- Returns an array of all defined functions
register_shutdown_function -- Register a function for execution on shutdown
register_tick_function -- Register a function for execution on each tick
unregister_tick_function -- De-register a function for execution on each tick

call_user_func_array

(PHP 4 >= 4.0.4, PHP 5)

call_user_func_array -- Call a user function given with an array of parameters

Description

mixed call_user_func_array ( callback function, array param_arr )

Call a user defined function given by function, with the parameters in param_arr. For example:

Esempio 1. call_user_func_array() example
<?php function debug($var, $val) { echo "***DEBUGGING\nVARIABLE: $var\nVALUE:"; if (is_array($val) || is_object($val) || is_resource($val)) { print_r($val); } else { echo "\n$val\n"; } echo "***\n"; } $c = mysql_connect(); $host = $_SERVER["SERVER_NAME"]; call_user_func_array('debug', array("host", $host)); call_user_func_array('debug', array("c", $c)); call_user_func_array('debug', array("_POST", $_POST)); ?>

See also call_user_func(), and information about the callback type

call_user_func

(PHP 3 >= 3.0.3, PHP 4, PHP 5)

call_user_func -- Call a user function given by the first parameter

Description

mixed call_user_func ( callback function [, mixed parameter [, mixed ...]] )

Call a user defined function given by the function parameter. Take the following:

<?php
function barber($type) 
{
    echo "You wanted a $type haircut, no problem";
}
call_user_func('barber', "mushroom");
call_user_func('barber', "shave");
?>

Object methods may also be invoked statically using this function by passing array($objectname, $methodname) to the function parameter.

<?php
class myclass {
    function say_hello() 
    {
        echo "Hello!\n";
    }
}

$classname = "myclass";

call_user_func(array($classname, 'say_hello'));
?>

Nota: Note that the parameters for call_user_func() are not passed by reference.

<?php
function increment(&$var)
{
    $var++;
}

$a = 0;
call_user_func('increment', $a);
echo $a; // 0

call_user_func_array('increment', array(&$a)); // You can use this instead
echo $a; // 1
?>

See also: is_callable(), call_user_func_array(), e information about the callback type.

create_function

(PHP 4 >= 4.0.1, PHP 5)

create_function -- Create an anonymous (lambda-style) function

Description

string create_function ( string args, string code )

Creates an anonymous function from the parameters passed, and returns a unique name for it. Usually the args will be passed as a single quote delimited string, and this is also recommended for the code. 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. \$avar.

You can use this function, to (for example) create a function from information gathered at run time:

Esempio 1. Creating an anonymous function with create_function()
<?php $newfunc = create_function('$a,$b', 'return "ln($a) + ln($b) = " . log($a * $b);'); echo "New anonymous function: $newfunc\n"; echo $newfunc(2, M_E) . "\n"; // outputs // New anonymous function: lambda_1 // ln(2) + ln(2.718281828459) = 1.6931471805599 ?>

Or, perhaps to have general handler function that can apply a set of operations to a list of parameters:

Esempio 2. Making a general processing function with create_function()
<?php function process($var1, $var2, $farr) { foreach ($farr as $f) { echo $f($var1, $var2) . "\n"; } } // create a bunch of math functions $f1 = 'if ($a >=0) {return "b*a^2 = ".$b*sqrt($a);} else {return false;}'; $f2 = "return \"min(b^2+a, a^2,b) = \".min(\$a*\$a+\$b,\$b*\$b+\$a);"; $f3 = 'if ($a > 0 && $b != 0) {return "ln(a)/b = ".log($a)/$b; } else { return false; }'; $farr = array( create_function('$x,$y', 'return "some trig: ".(sin($x) + $x*cos($y));'), create_function('$x,$y', 'return "a hypotenuse: ".sqrt($x*$x + $y*$y);'), create_function('$a,$b', $f1), create_function('$a,$b', $f2), create_function('$a,$b', $f3) ); echo "\nUsing the first array of anonymous functions\n"; echo "parameters: 2.3445, M_PI\n"; process(2.3445, M_PI, $farr); // now make a bunch of string processing functions $garr = array( create_function('$b,$a', 'if (strncmp($a, $b, 3) == 0) return "** \"$a\" '. 'and \"$b\"\n** Look the same to me! (looking at the first 3 chars)";'), create_function('$a,$b', '; return "CRCs: " . crc32($a) . " , ".crc32(b);'), create_function('$a,$b', '; return "similar(a,b) = " . similar_text($a, $b, &$p) . "($p%)";') ); echo "\nUsing the second array of anonymous functions\n"; process("Twas brilling and the slithy toves", "Twas the night", $garr); ?>
and when you run the code above, the output will be:
Using the first array of anonymous functions parameters: 2.3445, M_PI some trig: -1.6291725057799 a hypotenuse: 3.9199852871011 b*a^2 = 4.8103313314525 min(b^2+a, a^2,b) = 8.6382729035898 ln(a/b) = 0.27122299212594 Using the second array of anonymous functions ** "Twas the night" and "Twas brilling and the slithy toves" ** Look the same to me! (looking at the first 3 chars) CRCs: -725381282 , 1908338681 similar(a,b) = 11(45.833333333333%)

But perhaps the most common use for of lambda-style (anonymous) functions is to create callback functions, for example when using array_walk() or usort()

Esempio 3. Using anonymous functions as callback functions
<?php $av = array("the ", "a ", "that ", "this "); array_walk($av, create_function('&$v,$k', '$v = $v . "mango";')); print_r($av); ?>
outputs:
Array ( [0] => the mango [1] => a mango [2] => that mango [3] => this mango )
an array of strings ordered from shorter to longer
<?php $sv = array("small", "larger", "a big string", "it is a string thing"); print_r($sv); ?>
outputs:
Array ( [0] => small [1] => larger [2] => a big string [3] => it is a string thing )
sort it from longer to shorter
<?php usort($sv, create_function('$a,$b','return strlen($b) - strlen($a);')); print_r($sv); ?>
outputs:
Array ( [0] => it is a string thing [1] => a big string [2] => larger [3] => small )

func_get_arg

(PHP 4, PHP 5)

func_get_arg -- Return an item from the argument list

Description

mixed func_get_arg ( int arg_num )

Returns the argument which is at the arg_num'th offset into a user-defined function's argument list. Function arguments are counted starting from zero. func_get_arg() will generate a warning if called from outside of a function definition. This function cannot be used directly as a function parameter. Instead, its result may be assigned to a variable, which can then be passed to the function.

If arg_num is greater than the number of arguments actually passed, a warning will be generated and func_get_arg() will return FALSE.

Nota: Because this function depends on the current scope to determine parameter details, it cannot be used as a function parameter. If you must pass this value, assign the results to a variable, and pass the variable.

<?php
function foo() 
{
     $numargs = func_num_args();
     echo "Number of arguments: $numargs<br />\n";
     if ($numargs >= 2) {
     echo "Second argument is: " . func_get_arg(1) . "<br />\n";
     }
} 

foo (1, 2, 3);
?>

func_get_arg() may be used in conjunction with func_num_args() and func_get_args() to allow user-defined functions to accept variable-length argument lists.

func_get_args

(PHP 4, PHP 5)

func_get_args -- Returns an array comprising a function's argument list

Description

array func_get_args ( void )

Returns an array in which each element is a copy of the corresponding member of the current user-defined function's argument list. func_get_args() will generate a warning if called from outside of a function definition. This function cannot be used directly as a function parameter. Instead, its result may be assigned to a variable, which can then be passed to the function.

Nota: This function returns a copy of the passed arguments only, and does not account for default (non-passed) arguments.

Nota: Because this function depends on the current scope to determine parameter details, it cannot be used as a function parameter. If you must pass this value, assign the results to a variable, and pass the variable.

<?php
function foo() 
{
    $numargs = func_num_args();
    echo "Number of arguments: $numargs<br />\n";
    if ($numargs >= 2) {
        echo "Second argument is: " . func_get_arg(1) . "<br />\n";
    }
    $arg_list = func_get_args();
    for ($i = 0; $i < $numargs; $i++) {
        echo "Argument $i is: " . $arg_list[$i] . "<br />\n";
    }
} 

foo(1, 2, 3);
?>

func_get_args() may be used in conjunction with func_num_args() and func_get_arg() to allow user-defined functions to accept variable-length argument lists.

func_num_args

(PHP 4, PHP 5)

func_num_args -- Returns the number of arguments passed to the function

Description

int func_num_args ( void )

Returns the number of arguments passed into the current user-defined function. func_num_args() will generate a warning if called from outside of a user-defined function. This function cannot be used directly as a function parameter. Instead, its result may be assigned to a variable, which can then be passed to the function.

Nota: Because this function depends on the current scope to determine parameter details, it cannot be used as a function parameter. If you must pass this value, assign the results to a variable, and pass the variable.

<?php
function foo() 
{
    $numargs = func_num_args();
    echo "Number of arguments: $numargs\n";
} 

foo(1, 2, 3);    // Prints 'Number of arguments: 3'
?>

func_num_args() may be used in conjunction with func_get_arg() and func_get_args() to allow user-defined functions to accept variable-length argument lists.

function_exists

(PHP 3 >= 3.0.7, PHP 4, PHP 5)

function_exists -- Return TRUE if the given function has been defined

Description

bool function_exists ( string function_name )

Checks the list of defined functions, both built-in (internal) and user-defined, for function_name. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

<?php
if (function_exists('imap_open')) {
    echo "IMAP functions are available.<br />\n";
} else {
    echo "IMAP functions are not available.<br />\n";
}
?>

Note that a function name may exist even if the function itself is unusable due to configuration or compiling options (with the image functions being an example). Also note that function_exists() will return FALSE for constructs, such as include_once() and echo().

get_defined_functions

(PHP 4 >= 4.0.4, PHP 5)

get_defined_functions -- Returns an array of all defined functions

Description

array get_defined_functions ( void )

This function returns an multidimensional array containing a list of all defined functions, both built-in (internal) and user-defined. The internal functions will be accessible via $arr["internal"], and the user defined ones using $arr["user"] (see example below).

<?php
function myrow($id, $data) 
{
    return "<tr><th>$id</th><td>$data</td></tr>\n";
}

$arr = get_defined_functions();

print_r($arr);
?>

Will output something along the lines of:

Array
(
    [internal] => Array
        (
            [0] => zend_version
            [1] => func_num_args
            [2] => func_get_arg
            [3] => func_get_args
            [4] => strlen
            [5] => strcmp
            [6] => strncmp
            ...
            [750] => bcscale
            [751] => bccomp
        )

    [user] => Array
        (
            [0] => myrow
        )

)

register_shutdown_function

(PHP 3 >= 3.0.4, PHP 4, PHP 5)

register_shutdown_function -- Register a function for execution on shutdown

Description

void register_shutdown_function ( callback function [, mixed parameter [, mixed ...]] )

Registers the function named by function to be executed when script processing is complete.

Multiple calls to register_shutdown_function() can be made, and each will be called in the same order as they were registered. If you call exit() within one registered shutdown function, processing will stop completely and no other registered shutdown functions will be called.

In PHP 4.0.6 and earlier under Apache, the registered shutdown functions are called after the request has been completed (including sending any output buffers), so it is not possible to send output to the browser using echo() or print(), or retrieve the contents of any output buffers using ob_get_contents(). Since PHP 4.1, the shutdown functions are called as the part of the request so that it's possible to send the output from them. There is currently no way to process the data with output buffering functions in the shutdown function. Shutdown function is called after closing all opened output buffers thus, for example, its output will not be compressed if zlib.output_compression is enabled.

As of PHP 4, it is possible to pass parameters to the shutdown function by passing additional parameters to register_shutdown_function().

Nota: Typically undefined functions cause fatal errors in PHP, but when the function called with register_shutdown_function() is undefined, an error of level E_WARNING is generated instead. Also, for reasons internal to PHP, this error will refer to Unknown at line #0.

Nota: Working directory of the script can change inside the shutdown function under some web servers, e.g. Apache.

Nota: Shutdown function is called during the script shutdown so headers are always already sent.

See also auto_append_file, exit(), and the section on connection handling.

register_tick_function

(PHP 4 >= 4.0.3, PHP 5)

register_tick_function -- Register a function for execution on each tick

Description

bool register_tick_function ( callback function [, mixed arg [, mixed ...]] )

Registers the function named by func to be executed when a tick is called. Also, you may pass an array consisting of an object and a method as the func.

Esempio 1. register_tick_function() example
<?php // using a function as the callback register_tick_function('my_function', true); // using an object->method $object = new my_class(); register_tick_function(array(&$object, 'my_method'), true); ?>

Avvertimento

register_tick_function() should not be used with threaded webserver modules. Ticks are not working in ZTS mode and may crash your webserver.

unregister_tick_function

(PHP 4 >= 4.0.3, PHP 5)

unregister_tick_function -- De-register a function for execution on each tick

Description

void unregister_tick_function ( string function_name )

De-registers the function named by function_name so it is no longer executed when a tick is called.

XLV. Gettext

Introduzione

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.

Requisiti

To use these functions you must download and install the GNU gettext package from http://www.gnu.org/software/gettext/gettext.html

Installazione

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.

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

Questa estensione non definisce alcuna costante.

Sommario
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

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

Description

string bind_textdomain_codeset ( string domain, string codeset )

With bind_textdomain_codeset(), you can set in which encoding will be messages from domain returned by gettext() and similar functions.

bindtextdomain

(PHP 3 >= 3.0.7, PHP 4, PHP 5)

bindtextdomain -- Sets the path for a domain

Description

string bindtextdomain ( string domain, string directory )

string gettext ( string message )

This function returns a translated string if one is found in the translation table, or the submitted message if not found. You may use the underscore character '_' as an alias to this function.

Esempio 1. gettext()-check

<?php
// Set language to German
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");
?>

ngettext

(PHP 4 >= 4.2.0, PHP 5)

ngettext -- Plural version of gettext

Description

string ngettext ( string msgid1, string msgid2, int n )

ngettext() returns correct plural form of message identified by msgid1 and msgid2 for count n. Some languages have more than one form for plural messages dependent on the count.

Esempio 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 3 >= 3.0.7, PHP 4, PHP 5)

textdomain -- Sets the default domain

Descrizione

string textdomain ( string text_domain )

This function sets the domain to search within when calls are made to gettext(), usually the named after an application.

Elenco dei parametri

text_domain: The new message domain, or NULL to get the current setting without changing it

Valori restituiti

If successful, this function returns the current message domain, after possibly changing it.

XLVI. Funzioni GMP

Introduzione

Queste funzioni permettono di lavorare con numeri interi di lunghezza arbitraria usando le librerie GNU MP.

Queste funzioni sono state aggiunte in PHP 4.0.4.

Nota: Molte funzioni accettano argomenti numerici GMP, definiti come risorsepiù in basso. Comunque, molte di queste funzioni accetteranno anche normali argomenti numerici e stringhe, considerato ciò è quindi possibile convertire queste ultime in numero. Inoltre, se c'è una funzione che può operare velocemente su argomenti interi, questa potrebbe essere usata al posto della più lenta quando l'argomento fornito è un intero. Questo è fatto con chiarezza, così la logica vuole che tu possa utilizzare numeri interi in ogni funzione che richieda un numero GMP. Vedere anche la funzione gmp_init().

Avvertimento

Se desideri specificare un "large integer" come costante, scrivilo tra virgolette come stringa. Se non lo fai, PHP interpreterà l'"integer literal" immediatamente, con una possibile perdita di precisione, ancora prima che la libreria GMP venga richiamata.

Nota: Questo modulo non è disponibile su piattaforme Windows.

Requisiti

Puoi scaricare la libreria GMP dal sito http://www.swox.com/gmp/. Dove è possibile anche scaricare il manuale GMP.

Per usare queste funzioni è necessaria la versione 2 o superiore delle librerie GMP.

Installazione

Per potere utilizzare queste funzioni, occorre compilare il PHP con il supporto GMP utilizzando il parametro --with-gmp.

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

GMP_ROUND_ZERO (integer)
GMP_ROUND_PLUSINF (integer)
GMP_ROUND_MINUSINF (integer)

Esempi

Esempio 1. Funzione fattoriale usando GMP
<?php function fact ($x) { if ($x <= 1) { return 1; } else { return gmp_mul($x, fact($x-1)); } } echo gmp_strval (fact (1000)) . "\n"; ?>

Questo calcolerà il fattoriale di 1000 (numero abbastanza grande) molto velocemente.

Vedere anche:

Ulteriori funzioni matematiche sono elencate nelle sezioni BCMath Funzione Matematiche a Precisione Arbitraria e Funzioni Matematiche.

Sommario
gmp_abs -- Valore assoluto
gmp_add -- Somma di numeri
gmp_and -- AND logico
gmp_clrbit -- Pulisce bit
gmp_cmp -- Confronto di numeri
gmp_com -- Calcola il complemento a uno di 'a'
gmp_div_q -- Divide due numberi
gmp_div_qr -- Divide due numeri e restituisce quoziente e resto
gmp_div_r -- Resto di una divisione
gmp_div -- Divisione di numberi
gmp_divexact -- Divisione intera di numeri
gmp_fact -- Fattoriale
gmp_gcd -- Calcola il MCD
gmp_gcdext -- Calcola il MCD e moltiplicatori
gmp_hamdist -- Distanza dell'hamming
gmp_init -- Crea un numero GMP
gmp_intval -- Converte un numero GMP in un intero
gmp_invert -- Inversione di modulo
gmp_jacobi -- Simbolo di Jacobi
gmp_legendre -- Simbolo di Legendre
gmp_mod -- Modulo
gmp_mul -- Prodotto di numeri
gmp_neg -- Rende un numero negativo
gmp_or -- OR logico
gmp_perfect_square -- Controllo quadrato perfetto
gmp_popcount -- Conteggio della popolazione
gmp_pow -- Eleva un numero a potenza
gmp_powm -- Modulo di un elevamento a potenza.
gmp_prob_prime -- Controlla se il numero è "probabilmente primo"
gmp_random -- Generatore di numeri casuali
gmp_scan0 -- Ricerca per 0
gmp_scan1 -- Ricerca per 1
gmp_setbit -- Imposta bit
gmp_sign -- Segno di un numero
gmp_sqrt -- Radice quadrata
gmp_sqrtrem -- Radice quadrata con resto
gmp_strval -- Converte un numero GMP in una stringa
gmp_sub -- Sottrazione di numeri
gmp_xor -- XOR logico

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

gmp_div_q

(PHP 4 >= 4.0.4, PHP 5)

gmp_div_q -- Divide due numberi

Descrizione

resource gmp_div_q ( resource a, resource b [, int round] )

Divide a per b e restituisce un numero intero. L'arrotondamento del risultato, è definito dal round, che può avere i seguenti valori:

GMP_ROUND_ZERO: Il risultato è troncato verso 0.
GMP_ROUND_PLUSINF: Il risultato è arrotondato verso +infinito.
GMP_ROUND_MINUSINF: Il risultato è arrotondato verso -infinito.

Questa funzione può anche essere richiamata come gmp_div().

Vedere anche gmp_div_r(), gmp_div_qr()

gmp_div_qr

(PHP 4 >= 4.0.4, PHP 5)

gmp_div_qr -- Divide due numeri e restituisce quoziente e resto

Descrizione

array gmp_div_qr ( resource n, resource d [, int round] )

Questa funzione, esegue la divisione tra n e d , restituendo un array, il primo elemento è, [n/d] (il risultato intero della divisione) il secondo è (n - [n/d] * d) (cioè il resto della divisone).

Vedere la funzione gmp_div_q() per la descrizione dell'argomento round.

Esempio 1. Divisione di numeri GMP
<?php $a = gmp_init ("0x41682179fbf5"); $res = gmp_div_qr ($a, "0xDEFE75"); printf("Result is: q - %s, r - %s", gmp_strval ($res[0]), gmp_strval ($res[1])); ?>

Vedere anche gmp_div_q(), gmp_div_r().

gmp_div_r

(PHP 4 >= 4.0.4, PHP 5)

gmp_div_r -- Resto di una divisione

Descrizione

Crea un numero GMP partendo da un intero o da una stringa. La stringa può essere decimale o esadecimale. Nell'ultimo caso, la stringa dovrebbe iniziare con 0x.

Esempio 1. Creare un numero GMP
<?php $a = gmp_init (123456); $b = gmp_init ("0xFFFFDEBACDFEDF7200"); ?>

Nota: Non è necessario chiamare uesta funzione se si vogliono usare interi o stringhe al posto di numeri GMP nelle funzioni GMP, come gmp_add(). Se se questa conversione è possibile e necessaria, gli argomenti delle funzioni vengono automaticamente convertiti in numeri GMP, usando le stesse regole di gmp_init().

gmp_intval

(PHP 4 >= 4.0.4, PHP 5)

gmp_intval -- Converte un numero GMP in un intero

Descrizione

bool gmp_perfect_square ( resource a )

string gmp_strval ( resource gmpnumber [, int base] )

Converte un numero GMP in una stringa rappresentato in base base. La base di default è 10. Le basi consentite variano dal 2 al 36.

Esempio 1. Converte un numero GMP in una stringa
<?php $a = gmp_init("0x41682179fbf5"); printf ("Decimal: %s, 36-based: %s", gmp_strval($a), gmp_strval($a,36)); ?>

gmp_sub

(PHP 4 >= 4.0.4, PHP 5)

gmp_sub -- Sottrazione di numeri

Descrizione

resource gmp_sub ( resource a, resource b )

Sottrae b da a e restituisce il risultato.

gmp_xor

(PHP 4 >= 4.0.4, PHP 5)

gmp_xor -- XOR logico

Descrizione

resource gmp_xor ( resource a, resource b )

Calcola l'OR logico esclusivo (XOR) di due numeri GMP.

XLVII. Net_Gopher

Introduzione

The gopher protocol, as defined by RFC 1436, is generally considered the ancestor of the modern HTTP protocol. However, gopher was also intended to provide references to non-gopher resources including telnet, wais, nntp, and even http. This extension adds gopher support to PHP's URL Wrappers, and provides a helper function gopher_parsedir() to make sense of gopher formatted directory listings.

Requisiti

Installazione

Net_Gopher is installed through the usual PECL package installation process.

Prerequisite: PHP 4.3.0.
$ pear install Net_Gopher
Copy the resulting gopher.so to an appropriate location and add extension=gopher.so to your php.ini file or load it dynamically in your PHP script using dl("gopher.so");

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

Questa estensione non definisce alcuna costante.

Esempi

<?php
dl("gopher.so");

readfile("gopher://gopher.example.com/somedocument");
?>

Sommario
gopher_parsedir -- Translate a gopher formatted directory entry into an associative array.

gopher_parsedir

(PECL)

gopher_parsedir -- Translate a gopher formatted directory entry into an associative array.

Descrizione

array gopher_parsedir ( string dirent )

While gopher returns text/plain documents for actual document requests. A request to a directory (such as /) will return specially encoded series of lines with each line being one directory entry or information line.

Esempi

Esempio 1. Hypothetical output from gopher://gopher.example.com/
0All about my gopher site. /allabout.txt gopher.example.com 70 9A picture of my cat. /pics/cat.png gopher.example.com 70 1A collection of my writings. /stories gopher.example.com 70 hThe HTTP version of this site. URL:http://www.example.com gopher.example.com 70 1Mirror of this site in Spain. / gopher.ejemplo.co.es 70 iWelcome to my gopher site. error.host 1 iPlease select one of the options above error.host 1 iSend complaints to /dev/null error.host 1 iLong live gopher! error.host 1

In the example above, the root directory at gopher.example.com knows about one DOCUMENT identified by 0 located at gopher://gopher.example.com:70/allabout.txt. It also knows about two other directory (which have their own listing files) at gopher://gopher.exmaple.com:70/stories and at gopher://gopher.ejemplo.co.es:70/. In addition there is a binary file, a link to an HTTP url, and several informative lines.

By passing each line of the directory listing into gopher_parsedir(), an associative array is formed containing a parsed out version of the data.

Esempio 2. Using gopher_parsedir()
<?php dl("gopher.so"); $directory = file("gopher://gopher.example.com"); foreach($directory as $dirent) { print_r(gopher_parsedir($dirent)); } /* Expected Output --------------- Array ( [type] => 0 [title] => All about my gopher site. [path] => /allabout.txt [host] => gopher.example.com [port] => 70 ) Array ( [type] => 9 [title] => A picture of my cat. [path] => /pics/cat.png [host] => gopher.example.com [port] => 70 ) Array ( [type] => 1 [title] => A collection of my writings. [path] => /stories [host] => gopher.example.com [port] => 70 ) Array ( [type] => 254 [title] => The HTTP version of this site. [path] => URL:http://www.example.com [host] => gopher.example.com [port] => 70 ) Array ( [type] => 1 [title] => Mirror of this site in Spain. [path] => / [host] => gopher.ejemplo.co.es [port] => 70 ) Array ( [type] => 255 [title] => Welcome to my gopher site. [path] => [host] => error.host [port] => 1 ) Array ( [type] => 255 [title] => Please select one of the options above. [path] => [host] => error.host [port] => 1 ) Array ( [type] => 255 [title] => Send complaints to /dev/null [path] => [host] => error.host [port] => 1 ) Array ( [type] => 255 [title] => Long live gopher! [path] => [host] => error.host [port] => 1 ) */ ?>

The values given by type are associated with the following constants.

Tabella 1. Gopher Constants

Constant	Definition
`GOPHER_DOCUMENT`	Standard `text/plain` document.
`GOPHER_DIRECTORY`	A resource containing a gopher formatted directory listing.
`GOPHER_BINHEX`	A BinHex encoded binary file.
`GOPHER_DOSBINARY`	A DOS formatted binary archive.
`GOPHER_UUENCODED`	A UUEncoded file.
`GOPHER_BINARY`	A generic binary file.
`GOPHER_INFO`	An Informational entry
`GOPHER_HTTP`	A reference to an HTTP resource.
`GOPHER_UNKNOWN`	An unrecognized entry, the line will be returned in `data`.

XLVIII. Funzioni HTTP

Introduzione

Queste funzioni permettono di modificare l'output inviato verso un browser attraverso manipolazioni a livello di protocollo HTTP.

Requisiti

Non sono necessarie librerie esterne per utilizzare questo modulo.

Installazione

Non è necessaria nessuna installazione per usare queste funzioni, esse fanno parte del core di PHP.

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

Questa estensione non definisce alcuna costante.

Sommario
header -- Spedisce un header HTTP
headers_list -- Returns a list of response headers sent (or ready to send)
headers_sent -- Restituisce TRUE se gli header sono stati trasmessi.
setcookie -- Spedisce un cookie
setrawcookie -- Send a cookie without urlencoding the cookie value

header

(PHP 3, PHP 4, PHP 5)

header -- Spedisce un header HTTP

Descrizione

int header ( string string [, bool replace] )

header() si utilizza per inviare header HTTP. Per maggiorni informazioni riguardanti gli header HTTP si veda la risorsa HTTP 1.1 specification.

L'argomento opzionale replace indica se l'header inviato deve sostituirne uno simile spedito precedentemente, o accodarsi al primo dello stesso tipo. Per default la funzione sostituisce l'header precedente, ma se viene passato FALSE come secondo argomento vengono forzate intestazioni multiple. Per esempio:

header('WWW-Authenticate: Negotiate');
header('WWW-Authenticate: NTLM',false);

Ci sono due casi speciali di chiamate di header. Il primo è "Location". Location non trasmette solo un header al browser, ma anche un REDIRECT con codice di stato (302).

header("Location: http://www.php.net/"); /* Ridireziona il browser 
                                            al sito di PHP */
exit;                 /* Assicura che il codice sottostante 
                         non sia eseguito dopo il redirezionamento. */

Nota: HTTP/1.1 richiede un URI assoluto come argomento di Location: composto da schema, hostname, e path assoluto, ma alcuni clients possono accettare anche URIs relativi. E' possibile usare $HTTP_SERVER_VARS['HTTP_HOST'], $HTTP_SERVER_VARS['PHP_SELF'] e dirname() per creare URI assoluti da URI relativi in modo automatico:
header ("Location: http://".$HTTP_SERVER_VARS['HTTP_HOST']
                       ."/".dirname($HTTP_SERVER_VARS['PHP_SELF'])
                       ."/".$relative_url);

Il secondo caso speciale è esemplificato dalle intestazioni che iniziano con la stringa, "HTTP/" (le maiuscole non sono discriminanti), che è usato per inviare codici di stato HTTP. Per esempio, se si è configurato Apache per usare script PHP per la manipolazione di richieste fallite (usando la direttiva ErrorDocument), potete desiderare di assicurarvi che il vostro script generi il codice adeguato.

header ("HTTP/1.0 404 Not Found");

Nota: In PHP 3, questo funziona solo se PHP è compilato come modulo Apache. Potete ottenere lo stesso effetto usando l'header Status.
header("Status: 404 Not Found");

Spesso gli scrit PHP generano contenuti dinamici, se volete evitare che i contenuti vengano mantenuti nella cache di browser o proxy, potete forzare il loro comportamento con questa direttiva:

header("Expires: Mon, 26 Jul 1997 05:00:00 GMT");    // Data passata
header("Last-Modified: " . gmdate("D, d M Y H:i:s") . " GMT"); 
                                                     // sempre modificato
header("Cache-Control: no-store, no-cache, must-revalidate");  // HTTP/1.1
header("Cache-Control: post-check=0, pre-check=0", false);
header("Pragma: no-cache");                          // HTTP/1.0

Nota: E' possibile che alcune pagine rimangano in chache anche dopo l'uso degli header descritti sopra. Ci sono delle opzioni che l'utente può settare dal browser, capaci di modificare i comportamenti di default del caching. Per trasmettere efficacemente gli header descritti, bisogna che sia inattiva ogni regolazione che può forzare comportamenti contrari.
Inoltre, session_cache_limiter() e e la configurazione session.cache_limiter possono essere usate per generare automaticamente i corretti header relativi al caching durante l'uso delle sessioni.

Bisogna ricordare che la funzioneheader() va chiamata prima di qualsiasi output HTML o PHP (anche righe o spazi vuoti). E' un errore comune leggere files con funzioni include(), o require() (o altre funzioni capaci di accedere a files), che possano emettere in output spazi o linee vuote prima di una chiamata della funzione header(). Lo stesso problema esiste nell'utilizzare file PHP/HTML.

<?php require("user_logging.inc") ?>

<?php header ("Content-type: audio/x-pn-realaudio"); ?>
// Non funziona, notate le linee vuote sopra

Nota: In PHP 4, potete usare il buffering dell'output per aggirare questo problema, evitando ogni output al browser trattenedolo al server fino a che non gli si impone l'invio. Si può fare questa operazione chiamando ob_start() e ob_end_flush() nello script, o settando la direttiva di configurazione output_buffering nel file php.ini o nel file di configurazione del server.

Se desiderate che l'utente sia spinto a salvare i dati trasmessi per esempio utilizzando un file PDF, potete usare l'header Content-Disposition, che vi permette di dare un nome al file e forzare il browser a mostrare la finestra di dialogo save.

<?php
header("Content-type: application/pdf");
header("Content-Disposition: attachment; filename=downloaded.pdf");

/* ... manda in output un file pdf ... */

Nota: Per un bug di Microsoft Internet Explorer 4.01 qusto sistema non funziona. Non ci sono soluzioni. C'è un altro bug in Microsoft Internet Explorer 5.5 che impedisce il giusto funzionamento, ma è possibile risolverlo con l'upgrade del Service Pack 2 o superiore.

Vedi anche headers_sent(), setcookie(), e la sezione Autenticazione HTTP usando PHP.

headers_list

(PHP 5)

headers_list -- Returns a list of response headers sent (or ready to send)

Description

array headers_list ( void )

headers_list() will return a numerically indexed array of headers to be sent to the browser / client. To determine whether or not these headers have been sent yet, use headers_sent().

Esempio 1. Examples using headers_list()
<?php /* setcookie() will add a response header on its own */ setcookie('foo', 'bar'); /* Define a custom response header This will be ignored by most clients */ header("X-Sample-Test: foo"); /* Specify plain text content in our response */ header('Content-type: text/plain'); /* What headers are going to be sent? */ var_dump(headers_list()); ?>
this will output :
array(4) { [0]=> string(12) "X-Powered-By" [1]=> string(10) "Set-Cookie" [2]=> string(13) "X-Sample-Test" [3]=> string(12) "Content-type" }

headers_sent

(PHP 3 >= 3.0.8, PHP 4, PHP 5)

headers_sent -- Restituisce TRUE se gli header sono stati trasmessi.

Descrizione

bool headers_sent ( void )

Questa funzione restituisce TRUE se gli header HTTP sono stati spedite correttamente, FALSE in caso contrario.

Vedi anche header()

setcookie

(PHP 3, PHP 4, PHP 5)

setcookie -- Spedisce un cookie

Descrizione

int setcookie ( string name [, string value [, int expire [, string path [, string domain [, int secure]]]]] )

setcookie() definisce un cookie da inviare insieme alle altre informazioni di header. I cookie devono essere spediti prima di qualsiasi altra intestazione (questa è una restrizione dei cookies, non di PHP). E' necessario perciò chiamare la funzione setcookie() prima di qualsiasi tags, anche <html> o <head>.

Tutti gli argomenti della funzione eccetto name sono opzionali. Se viene passato alla funzione solo l'argomento name, il cookie registrato con quel nome verrà cancellato dal client su cui è archiviato. E' possibile sostituire gli argomenti che non si intende specificare utitlizzando una stringa vuota (""). Gli argomenti expire e secure che richiedono numeri interi, non possono essere omessi inserendo una stringa vuota, per questo scopo si usa (0). L'argomento expire è un normale intero Unix Timestamp ottenibile grazie alle funzioni time() o mktime(). secure sta ad indicare che il cookie dovrebbe essere trasmesso soltanto attraverso un collegamento sicuro di tipo HTTPS.

Errori comuni:

I cookie diventano disponibili soltanto dalla pagina successiva a quella che li ha generati, o dopo il ricaricamento di questa.
I cookie devono essere cancellati specificando gli stessi parametri con cui sono stati creati.

In PHP 3, chiamate successive di setcookie() nello stesso script sono eseguite in ordine inverso. Se state provando a cancellare un cookie prima dell' inserimento di un altro cookie, dovete creare il secondo prima della cancellazione del primo. In PHP 4, chiamate successive di setcookie() invece, sono eseguite secondo l'ordine di chiamata.

Alcuni esempi sul modo di spedire cookie:
Esempio 1. setcookie() esempi di spedizione/creazione
setcookie ("TestCookie", "Test Value"); setcookie ("TestCookie", $value,time()+3600); /* aspira in 1 ora */ setcookie ("TestCookie", $value,time()+3600, "/~rasmus/", ".utoronto.ca", 1);

Gli esempi mostrano come cancellare i cookie introdotti nell'esempio precedente:
Esempio 2. setcookie() esempi di cancellazione
setcookie ("TestCookie"); // set the expiration date to one hour ago setcookie ("TestCookie", "", time() - 3600); setcookie ("TestCookie", "", time() - 3600, "/~rasmus/", ".utoronto.ca", 1);
Per cancellare un cookie dovete assicurarvi che la data di scadenza del cookie sia già trascorsa, in questo modo il cookie verrà rimosso dal client.

Si noti che i valori salvati nei cookies sono automaticamente codificati per la trasmissione via URL (urlencoded) quando il cookie viene inviato, e che al momento del richiamo sono automaticamente decodificati e assegnati ad una variabile che ha lo stesso nome del cookie. Per vedere il contenuto di un cookie in uno script, si usa una di queste due sintassi:

echo $TestCookie;
echo $HTTP_COOKIE_VARS["TestCookie"];

Potete registrare array in un cookie usando la notazione degli array al posto del nome del cookie. Questo equivale alla spedizione di tanti cookie quanti sono gli elementi dell'array, ma si ha un vantaggio: quando il cookie è ricevuto, tutti i suoi valori sono ordinati in un singolo array che ha per nome il nome del cookie:

setcookie ("cookie[three]", "cookiethree");
setcookie ("cookie[two]", "cookietwo");
setcookie ("cookie[one]", "cookieone");
if (isset ($cookie)) {
    while (list ($name, $value) = each ($cookie)) {
        echo "$name == $value&lt;br>\n";
    }
}

Per saperne di più sui cookies, Netscape's cookie specification è la risorsa giusta http://wp.netscape.com/newsref/std/cookie_spec.html.

Microsoft Internet Explorer 4 con Service Pack 1 non crea correttamente cookie che hanno il parametro path specificato.

Netscape Communicator 4.05 e Microsoft Internet Explorer 3.x sembrano utilizzare in modo errato i cookie quando path ed expire non sono specificati.

setrawcookie

(PHP 5)

setrawcookie -- Send a cookie without urlencoding the cookie value

Description

bool setrawcookie ( string name [, string value [, int expire [, string path [, string domain [, bool secure]]]]] )

setrawcookie() is exactly the same as setcookie() except that the cookie value will not be automatically urlencoded when sent to the browser.

See also header(), setcookie() and the cookies section.

XLIX. Hyperwave Functions

Introduzione

Hyperwave has been developed at IICM in Graz. It started with the name Hyper-G and changed to Hyperwave when it was commercialised (in 1996).

Hyperwave is not free software. The current version, 5.5 is available at http://www.hyperwave.com/. A time limited version can be ordered for free (30 days).

Requisiti

This extension needs a Hyperwave server downloadable from http://www.hyperwave.com/.

Installazione

This PECL extension is not bundled with PHP.

In order to use these functions you must compile PHP with Hyperwave support by using the --with-hyperwave[=DIR] configure option.

Windows users will enable php_hyperwave.dll inside of php.ini in order to use these functions. You may download this PECL extension DLL from the PHP Downloads page or at http://snaps.php.net/.

Integration with Apache

The Hyperwave extension is best used when PHP is compiled as an Apache module. In such a case the underlying Hyperwave server can be hidden from users almost completely if Apache uses its rewriting engine. The following instructions will explain this.

Since PHP with Hyperwave support built into Apache is intended to replace the native Hyperwave solution based on Wavemaster, we will assume that the Apache server will only serve as a Hyperwave web interface for these examples. This is not necessary but it simplifies the configuration. The concept is quite simple. First of all you need a PHP script which evaluates the $_ENV['PATH_INFO'] variable and treats its value as the name of a Hyperwave object. Let's call this script 'Hyperwave'. The URL http://your.hostname/Hyperwave/name_of_object would than return the Hyperwave object with the name 'name_of_object'. Depending on the type of the object the script has to react accordingly. If it is a collection, it will probably return a list of children. If it is a document it will return the mime type and the content. A slight improvement can be achieved if the Apache rewriting engine is used. From the users point of view it would be more straight forward if the URL http://your.hostname/name_of_object would return the object. The rewriting rule is quite easy:

RewriteRule ^/(.*) /usr/local/apache/htdocs/HyperWave/$1 [L]

Now every URL relates to an object in the Hyperwave server. This causes a simple to solve problem. There is no way to execute a different script, e.g. for searching, than the 'Hyperwave' script. This can be fixed with another rewriting rule like the following:

RewriteRule ^/hw/(.*) /usr/local/apache/htdocs/hw/$1 [L]

This will reserve the directory /usr/local/apache/htdocs/hw for additional scripts and other files. Just make sure this rule is evaluated before the one above. There is just a little drawback: all Hyperwave objects whose name starts with 'hw/' will be shadowed. So, make sure you don't use such names. If you need more directories, e.g. for images just add more rules or place them all in one directory. Before you put those instructions, don't forget to turn on the rewriting engine with

RewriteEngine on

You will need scripts:

to return the object itself
to allow searching
to identify yourself
to set your profile
one for each additional function like to show the object attributes, to show information about users, to show the status of the server, etc.

As an alternative to the Rewrite Engine, you can also consider using the Apache ErrorDocument directive, but be aware, that ErrorDocument redirected pages cannot receive POST data.

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

Tabella 1. Hyperwave configuration options

Name	Default	Changeable	Changelog
hyperwave.allow_persistent	"0"	PHP_INI_SYSTEM	Available since PHP 4.3.2.
hyperwave.default_port	"418"	PHP_INI_ALL

Per maggiori dettagli sulle costanti PHP_INI_* vedere Appendice G.

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

HW_ATTR_LANG (integer)
HW_ATTR_NR (integer)
HW_ATTR_NONE (integer)

Todo

There are still some things to do:

The hw_InsertDocument has to be split into hw_insertobject() and hw_putdocument().
The names of several functions are not fixed, yet.
Most functions require the current connection as its first parameter. This leads to a lot of typing, which is quite often not necessary if there is just one open connection. A default connection will improve this.
Conversion form object record into object array needs to handle any multiple attribute.

Sommario
hw_Array2Objrec -- Convert attributes from object array to object record
hw_changeobject -- Changes attributes of an object (obsolete)
hw_Children -- Object ids of children
hw_ChildrenObj -- Object records of children
hw_Close -- Closes the Hyperwave connection
hw_Connect -- Opens a connection
hw_connection_info -- Prints information about the connection to Hyperwave server
hw_cp -- Copies objects
hw_Deleteobject -- Deletes object
hw_DocByAnchor -- Object id object belonging to anchor
hw_DocByAnchorObj -- Object record object belonging to anchor
hw_Document_Attributes -- Object record of hw_document
hw_Document_BodyTag -- Body tag of hw_document
hw_Document_Content -- Returns content of hw_document
hw_Document_SetContent -- Sets/replaces content of hw_document
hw_Document_Size -- Size of hw_document
hw_dummy -- Hyperwave dummy function
hw_EditText -- Retrieve text document
hw_Error -- Error number
hw_ErrorMsg -- Returns error message
hw_Free_Document -- Frees hw_document
hw_GetAnchors -- Object ids of anchors of document
hw_GetAnchorsObj -- Object records of anchors of document
hw_GetAndLock -- Return object record and lock object
hw_GetChildColl -- Object ids of child collections
hw_GetChildCollObj -- Object records of child collections
hw_GetChildDocColl -- Object ids of child documents of collection
hw_GetChildDocCollObj -- Object records of child documents of collection
hw_GetObject -- Object record
hw_GetObjectByQuery -- Search object
hw_GetObjectByQueryColl -- Search object in collection
hw_GetObjectByQueryCollObj -- Search object in collection
hw_GetObjectByQueryObj -- Search object
hw_GetParents -- Object ids of parents
hw_GetParentsObj -- Object records of parents
hw_getrellink -- Get link from source to dest relative to rootid
hw_GetRemote -- Gets a remote document
hw_getremotechildren -- Gets children of remote document
hw_GetSrcByDestObj -- Returns anchors pointing at object
hw_GetText -- Retrieve text document
hw_getusername -- Name of currently logged in user
hw_Identify -- Identifies as user
hw_InCollections -- Check if object ids in collections
hw_Info -- Info about connection
hw_InsColl -- Insert collection
hw_InsDoc -- Insert document
hw_insertanchors -- Inserts only anchors into text
hw_InsertDocument -- Upload any document
hw_InsertObject -- Inserts an object record
hw_mapid -- Maps global id on virtual local id
hw_Modifyobject -- Modifies object record
hw_mv -- Moves objects
hw_New_Document -- Create new document
hw_objrec2array -- Convert attributes from object record to object array
hw_Output_Document -- Prints hw_document
hw_pConnect -- Make a persistent database connection
hw_PipeDocument -- Retrieve any document
hw_Root -- Root object id
hw_setlinkroot -- Set the id to which links are calculated
hw_stat -- Returns status string
hw_Unlock -- Unlock object
hw_Who -- List of currently logged in users

hw_Array2Objrec

(PHP 3 >= 3.0.4, PHP 4, PECL)

hw_Array2Objrec -- Convert attributes from object array to object record

Description

string hw_array2objrec ( array object_array )

Converts an object_array into an object record. Multiple attributes like 'Title' in different languages are treated properly.

hw_changeobject

(PHP 3 >= 3.0.3, PHP 4, PECL)

hw_changeobject -- Changes attributes of an object (obsolete)

Description

bool hw_changeobject ( int link, int objid, array attributes )

string hw_document_attributes ( int hw_document )

Returns the object record of the document.

For backward compatibility, hw_documentattributes() is also accepted. This is deprecated, however.

hw_Document_BodyTag

(PHP 3 >= 3.0.3, PHP 4, PECL)

hw_Document_BodyTag -- Body tag of hw_document

Description

string hw_document_bodytag ( int hw_document [, string prefix] )

int hw_document_size ( int hw_document )

Returns the size in bytes of the document.

For backward compatibility, hw_documentsize() is also accepted. This is deprecated, however.

hw_dummy

(PHP 3 >= 3.0.3, PHP 4, PECL)

hw_dummy -- Hyperwave dummy function

Description

mixed hw_getobject ( int connection, mixed objectID [, string query] )

Returns the object record for the object with ID objectID if the second parameter is an integer. If the second parameter is an array of integer the function will return an array of object records. In such a case the last parameter is also evaluated which is a query string.

The query string has the following syntax:

<expr> ::= "(" <expr> ")" |

"!" <expr> | /* NOT */

<expr> "||" <expr> | /* OR */

<expr> "&&" <expr> | /* AND */

<attribute> ::= /* any attribute name (Title, Author, DocumentType ...) */

<operator> ::= "=" | /* equal */

"<" | /* less than (string compare) */

array hw_getparents ( int connection, int objectID )

Returns an indexed array of object ids. Each object id belongs to a parent of the object with ID objectID.

hw_GetParentsObj

(PHP 3 >= 3.0.3, PHP 4, PECL)

hw_GetParentsObj -- Object records of parents

Description

array hw_getparentsobj ( int connection, int objectID )

Returns an indexed array of object records plus an associated array with statistical information about the object records. The associated array is the last entry of the returned array. Each object record belongs to a parent of the object with ID objectID.

hw_getrellink

(PHP 3 >= 3.0.3, PHP 4, PECL)

hw_getrellink -- Get link from source to dest relative to rootid

Description

string hw_getrellink ( int link, int rootid, int sourceid, int destid )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

hw_InsertDocument

(PHP 3 >= 3.0.3, PHP 4, PECL)

hw_InsertDocument -- Upload any document

bool hw_modifyobject ( int connection, int object_to_change, array remove, array add [, int mode] )

This command allows to remove, add, or modify individual attributes of an object record. The object is specified by the Object ID object_to_change. The first array remove is a list of attributes to remove. The second array add is a list of attributes to add. In order to modify an attribute one will have to remove the old one and add a new one. hw_modifyobject() will always remove the attributes before it adds attributes unless the value of the attribute to remove is not a string or array.

The last parameter determines if the modification is performed recursively. 1 means recursive modification. If some of the objects cannot be modified they will be skipped without notice. hw_error() may not indicate an error though some of the objects could not be modified.

The keys of both arrays are the attributes name. The value of each array element can either be an array, a string or anything else. If it is an array each attribute value is constructed by the key of each element plus a colon and the value of each element. If it is a string it is taken as the attribute value. An empty string will result in a complete removal of that attribute. If the value is neither a string nor an array but something else, e.g. an integer, no operation at all will be performed on the attribute. This is necessary if you want to add a completely new attribute not just a new value for an existing attribute. If the remove array contained an empty string for that attribute, the attribute would be tried to be removed which would fail since it doesn't exist. The following addition of a new value for that attribute would also fail. Setting the value for that attribute to e.g. 0 would not even try to remove it and the addition will work.

If you would like to change the attribute 'Name' with the current value 'books' into 'articles' you will have to create two arrays and call hw_modifyobject().
Esempio 1. modifying an attribute
<?php // $connect is an existing connection to the Hyperwave server // $objid is the ID of the object to modify $remarr = array("Name" => "books"); $addarr = array("Name" => "articles"); $hw_modifyobject($connect, $objid, $remarr, $addarr); ?>
In order to delete/add a name=value pair from/to the object record just pass the remove/add array and set the last/third parameter to an empty array. If the attribute is the first one with that name to add, set attribute value in the remove array to an integer.
Esempio 2. adding a completely new attribute
<?php // $connect is an existing connection to the Hyperwave server // $objid is the ID of the object to modify $remarr = array("Name" => 0); $addarr = array("Name" => "articles"); $hw_modifyobject($connect, $objid, $remarr, $addarr); ?>

Nota: Multilingual attributes, e.g. 'Title', can be modified in two ways. Either by providing the attributes value in its native form 'language':'title' or by providing an array with elements for each language as described above. The above example would than be:

Esempio 3. modifying Title attribute

<?php
       $remarr = array("Title" => "en:Books");
       $addarr = array("Title" => "en:Articles");
       $hw_modifyobject($connect, $objid, $remarr, $addarr);
?>

Esempio 4. modifying Title attribute

<?php
       $remarr = array("Title" => array("en" => "Books"));
       $addarr = array("Title" => array("en" => "Articles", "ge"=>"Artikel"));
       $hw_modifyobject($connect, $objid, $remarr, $addarr);
?>

This removes the English title 'Books' and adds the English title 'Articles' and the German title 'Artikel'.

Esempio 5. removing attribute

<?php
       $remarr = array("Title" => "");
       $addarr = array("Title" => "en:Articles");
       $hw_modifyobject($connect, $objid, $remarr, $addarr);
?>

Nota: This will remove all attributes with the name 'Title' and adds a new 'Title' attribute. This comes in handy if you want to remove attributes recursively.

Nota: If you need to delete all attributes with a certain name you will have to pass an empty string as the attribute value.

Nota: Only the attributes 'Title', 'Description' and 'Keyword' will properly handle the language prefix. If those attributes don't carry a language prefix, the prefix 'xx' will be assigned.

Nota: The 'Name' attribute is somewhat special. In some cases it cannot be complete removed. You will get an error message 'Change of base attribute' (not clear when this happens). Therefore you will always have to add a new Name first and than remove the old one.

Nota: You may not surround this function by calls to hw_getandlock() and hw_unlock(). hw_modifyobject() does this internally.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

hw_mv

(PHP 3 >= 3.0.3, PHP 4, PECL)

hw_mv -- Moves objects

Description

int hw_mv ( int connection, array object_id_array, int source_id, int destination_id )

Moves the objects with object ids as specified in the second parameter from the collection with id source_id to the collection with the id destination_id. If the destination id is 0 the objects will be unlinked from the source collection. If this is the last instance of that object it will be deleted. If you want to delete all instances at once, use hw_deleteobject().

bool hw_output_document ( int hw_document )

Prints the document without the BODY tag.

For backward compatibility, hw_outputdocument() is also accepted. This is deprecated, however.

hw_pConnect

(PHP 3 >= 3.0.3, PHP 4, PECL)

hw_pConnect -- Make a persistent database connection

Description

int hw_pconnect ( string host, int port [, string username, string password] )

Returns a connection index on success, or FALSE if the connection could not be made. Opens a persistent connection to a Hyperwave server. Each of the arguments should be a quoted string, except for the port number. The username and password arguments are optional and can be left out. In such a case no identification with the server will be done. It is similar to identify as user anonymous. This function returns a connection index that is needed by other Hyperwave functions. You can have multiple persistent connections open at once.

hw_PipeDocument

(PHP 3 >= 3.0.3, PHP 4, PECL)

hw_PipeDocument -- Retrieve any document

Description

int hw_pipedocument ( int connection, int objectID [, array url_prefixes] )

Returns the Hyperwave document with object ID objectID. If the document has anchors which can be inserted, they will have been inserted already. The document will be transferred via a special data connection which does not block the control connection.

See also hw_gettext() for more on link insertion, hw_free_document(), hw_document_size(), hw_document_bodytag(), and hw_output_document().

hw_Root

(PHP 3 >= 3.0.3, PHP 4, PECL)

hw_Root -- Root object id

bool hw_unlock ( int connection, int objectID )

Unlocks a document, so other users regain access.

hw_Who

(PHP 3 >= 3.0.3, PHP 4, PECL)

hw_Who -- List of currently logged in users

Description

array hw_who ( int connection )

Returns an array of users currently logged into the Hyperwave server. Each entry in this array is an array itself containing the elements id, name, system, onSinceDate, onSinceTime, TotalTime and self. 'self' is 1 if this entry belongs to the user who initiated the request.

L. Hyperwave API Functions

Introduzione

Hyperwave has been developed at IICM in Graz. It started with the name Hyper-G and changed to Hyperwave when it was commercialised (in 1996).

Hyperwave is not free software. The current version, 5.5, is available at http://www.hyperwave.com/. A time limited version can be ordered for free (30 days).

Requisiti

Since 2001 there is a Hyperwave SDK available. It supports Java, JavaScript and C++. This PHP Extension is based on the C++ interface. In order to activate the hwapi support in PHP you will have to install the Hyperwave SDK first.

Installazione

After installing the Hyperwave SDK, configure PHP with --with-hwapi[=DIR].

Integration with Apache

The integration with Apache and possible other servers is already described in the Hyperwave module which has been the first extension to connect a Hyperwave Server.

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

Tabella 1. Hyperwave API configuration options

Name	Default	Changeable	Changelog
hwapi.allow_persistent	"0"	PHP_INI_SYSTEM

Per maggiori dettagli sulle costanti PHP_INI_* vedere Appendice G.

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

Questa estensione non definisce alcuna costante.

Classes

The API provided by the HW_API extension is fully object oriented. It is very similar to the C++ interface of the Hyperwave SDK. It consist of the following classes.

HW_API
HW_API_Object
HW_API_Attribute
HW_API_Error
HW_API_Content
HW_API_Reason

Some basic classes like HW_API_String, HW_API_String_Array, etc., which exist in the Hyperwave SDK have not been implemented since PHP has powerful replacements for them.

Each class has certain method, whose names are identical to its counterparts in the Hyperwave SDK. Passing arguments to this function differs from all the other PHP extensions but is close to the C++ API of the HW SDK. Instead of passing several parameters they are all put into an associated array and passed as one parameter. The names of the keys are identical to those documented in the HW SDK. The common parameters are listed below. If other parameters are required they will be documented if needed.

objectIdentifier The name or id of an object, e.g. "rootcollection", "0x873A8768 0x00000002".
parentIdentifier The name or id of an object which is considered to be a parent.
object An instance of class HW_API_Object.
parameters An instance of class HW_API_Object.
version The version of an object.
mode An integer value determine the way an operation is executed.
attributeSelector Any array of strings, each containing a name of an attribute. This is used if you retrieve the object record and want to include certain attributes.
objectQuery A query to select certain object out of a list of objects. This is used to reduce the number of objects which was delivered by a function like hw_api->children() or hw_api->find().

Nota: Methods returning boolean can return TRUE, FALSE or HW_API_Error object.

Sommario
hw_api_attribute->key -- Returns key of the attribute
hw_api_attribute->langdepvalue -- Returns value for a given language
hw_api_attribute->value -- Returns value of the attribute
hw_api_attribute->values -- Returns all values of the attribute
hw_api_attribute -- Creates instance of class hw_api_attribute
hw_api->checkin -- Checks in an object
hw_api->checkout -- Checks out an object
hw_api->children -- Returns children of an object
hw_api_content->mimetype -- Returns mimetype
hw_api_content->read -- Read content
hw_api->content -- Returns content of an object
hw_api->copy -- Copies physically
hw_api->dbstat -- Returns statistics about database server
hw_api->dcstat -- Returns statistics about document cache server
hw_api->dstanchors -- Returns a list of all destination anchors
hw_api->dstofsrcanchor -- Returns destination of a source anchor
hw_api_error->count -- Returns number of reasons
hw_api_error->reason -- Returns reason of error
hw_api->find -- Search for objects
hw_api->ftstat -- Returns statistics about fulltext server
hwapi_hgcsp -- Returns object of class hw_api
hw_api->hwstat -- Returns statistics about Hyperwave server
hw_api->identify -- Log into Hyperwave Server
hw_api->info -- Returns information about server configuration
hw_api->insert -- Inserts a new object
hw_api->insertanchor -- Inserts a new object of type anchor
hw_api->insertcollection -- Inserts a new object of type collection
hw_api->insertdocument -- Inserts a new object of type document
hw_api->link -- Creates a link to an object
hw_api->lock -- Locks an object
hw_api->move -- Moves object between collections
hw_api_content -- Create new instance of class hw_api_content
hw_api_object->assign -- Clones object
hw_api_object->attreditable -- Checks whether an attribute is editable
hw_api_object->count -- Returns number of attributes
hw_api_object->insert -- Inserts new attribute
hw_api_object -- Creates a new instance of class hw_api_object
hw_api_object->remove -- Removes attribute
hw_api_object->title -- Returns the title attribute
hw_api_object->value -- Returns value of attribute
hw_api->object -- Retrieve attribute information
hw_api->objectbyanchor -- Returns the object an anchor belongs to
hw_api->parents -- Returns parents of an object
hw_api_reason->description -- Returns description of reason
hw_api_reason->type -- Returns type of reason
hw_api->remove -- Delete an object
hw_api->replace -- Replaces an object
hw_api->setcommittedversion -- Commits version other than last version
hw_api->srcanchors -- Returns a list of all source anchors
hw_api->srcsofdst -- Returns source of a destination object
hw_api->unlock -- Unlocks a locked object
hw_api->user -- Returns the own user object
hw_api->userlist -- Returns a list of all logged in users

HW_API_CHECKIN_NORMAL: Checks in and commits the object. The object must be a document.
HW_API_CHECKIN_RECURSIVE: If the object to check in is a collection, all children will be checked in recursively if they are documents. Trying to check in a collection would result in an error.
HW_API_CHECKIN_FORCE_VERSION_CONTROL: Checks in an object even if it is not under version control.
HW_API_CHECKIN_REVERT_IF_NOT_CHANGED: Check if the new version is different from the last version. Unless this is the case the object will be checked in.
HW_API_CHECKIN_KEEP_TIME_MODIFIED: Keeps the time modified from the most recent object.
HW_API_CHECKIN_NO_AUTO_COMMIT: The object is not automatically committed on check-in.

hw_api->checkout

(no version information, might be only in CVS)

hw_api->checkout -- Checks out an object

Description

bool hw_api->checkout ( array parameter )

This function checks out an object or a whole hierarchy of objects. The parameters array contains the required element 'objectIdentifier' and the optional element 'version', 'mode' and 'objectQuery'. 'mode' can be one of the following values:

HW_API_CHECKIN_NORMAL: Checks out an object. The object must be a document.
HW_API_CHECKIN_RECURSIVE: If the object to check out is a collection, all children will be checked out recursively if they are documents. Trying to check out a collection would result in an error.

hw_api->children

(no version information, might be only in CVS)

hw_api->children -- Returns children of an object

Description

array hw_api->children ( array parameter )

hw_api_object hw_api->ftstat ( array parameter )

hwapi_hgcsp

(no version information, might be only in CVS)

hwapi_hgcsp -- Returns object of class hw_api

Description

HW_API hwapi_hgcsp ( string hostname [, int port] )

Opens a connection to the Hyperwave server on host hostname. The protocol used is HGCSP. If you do not pass a port number, 418 is used.

hw_api->hwstat

(no version information, might be only in CVS)

hw_api->hwstat -- Returns statistics about Hyperwave server

Description

hw_api_object hw_api->hwstat ( array parameter )

hw_api->identify

(no version information, might be only in CVS)

hw_api->identify -- Log into Hyperwave Server

Description

bool hw_api->identify ( array parameter )

Logs into the Hyperwave Server. The parameter array must contain the elements 'username' and 'password'.

The return value will be an object of type HW_API_Error if identification failed or TRUE if it was successful.

hw_api->info

(no version information, might be only in CVS)

hw_api->info -- Returns information about server configuration

Description

array hw_api->info ( array parameter )

hw_api->insert

(no version information, might be only in CVS)

hw_api->insert -- Inserts a new object

Description

hw_api_object hw_api->insert ( array parameter )

Insert a new object. The object type can be user, group, document or anchor. Depending on the type other object attributes has to be set. The parameter array contains the required elements 'object' and 'content' (if the object is a document) and the optional parameters 'parameters', 'mode' and 'attributeSelector'. The 'object' must contain all attributes of the object. 'parameters' is an object as well holding further attributes like the destination (attribute key is 'Parent'). 'content' is the content of the document. 'mode' can be a combination of the following flags:

HW_API_INSERT_NORMAL: The object in inserted into the server.
HW_API_INSERT_FORCE_VERSION_CONTROL
HW_API_INSERT_AUTOMATIC_CHECKOUT
HW_API_INSERT_PLAIN
HW_API_INSERT_KEEP_TIME_MODIFIED
HW_API_INSERT_DELAY_INDEXING

The function returns TRUE on success or an error object.

hw_api->lock

(no version information, might be only in CVS)

hw_api->lock -- Locks an object

Description

bool hw_api->lock ( array parameter )

Locks an object for exclusive editing by the user calling this function. The object can be only unlocked by this user or the system user. The parameter array contains the required element 'objectIdentifier' and the optional parameters 'mode' and 'objectquery'. 'mode' determines how an object is locked. HW_API_LOCK_NORMAL means, an object is locked until it is unlocked. HW_API_LOCK_RECURSIVE is only valid for collection and locks all objects within the collection and possible subcollections. HW_API_LOCK_SESSION means, an object is locked only as long as the session is valid.

hw_api->move

(no version information, might be only in CVS)

hw_api->move -- Moves object between collections

(no version information, might be only in CVS)

hw_api->objectbyanchor -- Returns the object an anchor belongs to

Description

hw_api_object hw_api->objectbyanchor ( array parameter )

This function retrieves an object the specified anchor belongs to. The parameter array contains the required element 'objectIdentifier' and the optional element 'attributeSelector'.

hw_api->parents

(no version information, might be only in CVS)

hw_api->parents -- Returns parents of an object

Description

array hw_api->parents ( array parameter )

hw_api_object hw_api->replace ( array parameter )

Replaces the attributes and the content of an object The parameter array contains the required elements 'objectIdentifier' and 'object' and the optional parameters 'content', 'parameters', 'mode' and 'attributeSelector'. 'objectIdentifier' contains the object to be replaced. 'object' contains the new object. 'content' contains the new content. 'parameters' contain extra information for HTML documents. HTML_Language is the letter abbreviation of the language of the title. HTML_Base sets the base attribute of the HTML document. 'mode' can be a combination of the following flags:

HW_API_REPLACE_NORMAL: The object on the server is replace with the object passed.
HW_API_REPLACE_FORCE_VERSION_CONTROL
HW_API_REPLACE_AUTOMATIC_CHECKOUT
HW_API_REPLACE_AUTOMATIC_CHECKIN
HW_API_REPLACE_PLAIN
HW_API_REPLACE_REVERT_IF_NOT_CHANGED
HW_API_REPLACE_KEEP_TIME_MODIFIED

hw_api->setcommittedversion

(no version information, might be only in CVS)

hw_api->setcommittedversion -- Commits version other than last version

Description

hw_api_object hw_api->setcommittedversion ( array parameter )

bool hw_api->unlock ( array parameter )

Unlocks a locked object. Only the user who has locked the object and the system user may unlock an object. The parameter array contains the required element 'objectIdentifier' and the optional parameters 'mode' and 'objectquery'. The meaning of 'mode' is the same as in function hwapi_lock().

Returns TRUE on success or an object of class HW_API_Error.

hw_api->user

(no version information, might be only in CVS)

hw_api->user -- Returns the own user object

Description

hw_api_object hw_api->user ( array parameter )

hw_api->userlist

(no version information, might be only in CVS)

hw_api->userlist -- Returns a list of all logged in users

Description

array hw_api->userlist ( array parameter )

LI. IBM DB2, Cloudscape and Apache Derby Functions

Introduzione

These functions enable you to access IBM DB2 Universal Database, IBM Cloudscape, and Apache Derby databases using the DB2 Call Level Interface (DB2 CLI).

Requisiti

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
If you do not set this option in php.ini, you must issue the following command to modify your environment variables to enable access to DB2:
bash$ source /home/db2inst1/sqllib/db2profile
To enable your PHP-enabled Web server to access these functions, you must either set the ibm_db2.instance_name configuration option in php.ini, or source the DB2 instance environment in your Web server start script (typically /etc/init.d/httpd or /etc/init.d/apache).

Installazione

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 Capitolo 7 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
The configure command defaults to /opt/IBM/db2/V8.1.

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

Tabella 1. ibm_db2 Opioni di configurazione

Nome	Default	Modificabile	Changelog
ibm_db2.binmode	"1"	PHP_INI_ALL
ibm_db2.instance_name	NULL	PHP_INI_SYSTEM

Breve descrizione dei parametri di configurazione.

ibm_db2.binmode integer

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.instance_name string

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.

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

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 NULL value.
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 or output.
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.

Tipi di risorse

The ibm_db2 extension returns connection resources, statement resources, and result set resources.

Sommario
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_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_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_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_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

db2_autocommit

(PECL)

db2_autocommit -- Returns or sets the AUTOCOMMIT state for a database connection

Descrizione

mixed db2_autocommit ( resource connection [, bool value] )

Sets or gets the AUTOCOMMIT behavior of the specified connection resource.

Elenco dei parametri

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.

Valori restituiti

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. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 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."; } ?>
Il precedente esempio visualizzerà:
0 -- AUTOCOMMIT is off.

Esempio 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."; } ?>
Il precedente esempio visualizzerà:
Turning AUTOCOMMIT on succeeded. 1 -- AUTOCOMMIT is on.

Vedere anche:

db2_pconnect()

db2_bind_param

(PECL)

db2_bind_param -- Binds a PHP variable to an SQL statement parameter

Descrizione

bool db2_bind_param ( resource stmt, int parameter-number, string variable-name [, int parameter-type [, int data-type [, int precision [, int scale]]]] )

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().

Elenco dei parametri

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).
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.
scale: Specifies the scale with which the variable should be bound to the database.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 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"; } } ?>
Il precedente esempio visualizzerà:
Pook, cat, 3.2 Rickety Ride, goat, 9.7 Peaches, dog, 12.3

Esempio 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
In addition, the stored procedure returns a result set consisting of the animals listed in alphabetic order starting at the animal corresponding to the input value of the first parameter and ending at the animal corresponding to the input value of the second parameter.
<?php $sql = 'CALL match_animal(?, ?, ?)'; $conn = db2_connect($database, $user, $password); $stmt = db2_prepare($conn, $sql); $name = "Peaches"; $second_name = "Rickety Ride"; 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"; } } ?>
Il precedente esempio visualizzerà:
Values of bound parameters _before_ CALL: 1: Peaches 2: Rickety Ride 3: 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

Vedere anche:

db2_client_info

(no version information, might be only in CVS)

db2_client_info -- Returns an object with properties that describe the DB2 database client

Descrizione

object db2_client_info ( resource 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:

Tabella 1. 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: MINIMUM Supports the minimum ODBC SQL grammar. CORE Supports the core ODBC SQL grammar. EXTENDED Supports extended ODBC SQL grammar.
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".

Elenco dei parametri

connection: Specifies an active DB2 client connection.

Valori restituiti

Returns an object on a successful call. Returns FALSE on failure.

Esempi

Esempio 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); ?>
Il precedente esempio visualizzerà:
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)

Vedere anche:

db2_server_info()

db2_close

(PECL)

db2_close -- Closes a database connection

Descrizione

bool db2_close ( resource 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.

Elenco dei parametri

connection: Specifies an active DB2 client connection.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 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."; } ?>
Il precedente esempio visualizzerà:
Connection was successfully closed.

Vedere anche:

db2_pconnect()

db2_column_privileges

(PECL)

db2_column_privileges -- Returns a result set listing the columns and associated privileges for a table

Descrizione

resource db2_column_privileges ( resource connection [, string qualifier [, string schema [, string table-name [, string column-name]]]] )

Returns a result set listing the columns and associated privileges for a table.

Elenco dei parametri

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 NULL or an empty string.
schema: The schema which contains the tables. To match all schemas, pass NULL or an empty string.
table-name: The name of the table or view. To match all tables in the database, pass NULL or an empty string.
column-name: The name of the column. To match all columns in the table, pass NULL or an empty string.

Valori restituiti

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.

Vedere anche:

db2_columns

(PECL)

db2_columns -- Returns a result set listing the columns and associated metadata for a table

Descrizione

resource db2_columns ( resource connection [, string qualifier [, string schema [, string table-name [, string column-name]]]] )

Returns a result set listing the columns and associated metadata for a table.

Elenco dei parametri

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 NULL or 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 NULL or an empty string.
column-name: The name of the column. To match all columns in the table, pass NULL or an empty string.

Valori restituiti

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.

Vedere anche:

db2_commit

(PECL)

db2_commit -- Commits a transaction

Descrizione

bool db2_commit ( resource 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.

Nota: If the specified connection resource is a persistent connection, all transactions in progress for all applications using that persistent connection will be committed. For this reason, persistent connections are not recommended for use in applications that require transactions.

Elenco dei parametri

connection: A valid database connection resource variable as returned from db2_connect() or db2_pconnect().

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

db2_autocommit()

db2_rollback()

db2_conn_error

(PECL)

db2_conn_error -- Returns a string containing the SQLSTATE returned by the last connection attempt

Descrizione

string db2_conn_error ( [resource 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 '? sqlstate-value'. You can also call db2_conn_errormsg() to retrieve an explicit error message and the associated SQLCODE value.

Elenco dei parametri

connection: A connection resource associated with a connection that initially succeeded, but which over time became invalid.

Valori restituiti

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.

Esempi

Esempio 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(); } ?>
Il precedente esempio visualizzerà:
SQLSTATE value: 08001

Vedere anche:

db2_conn_errormsg()

db2_conn_errormsg

(PECL)

db2_conn_errormsg -- Returns the last connection error message and SQLCODE value

Descrizione

string db2_conn_errormsg ( [resource 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.

Elenco dei parametri

connection: A connection resource associated with a connection that initially succeeded, but which over time became invalid.

Valori restituiti

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.

Esempi

Esempio 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(); } ?>
Il precedente esempio visualizzerà:
[IBM][CLI Driver] SQL1013N The database alias name or database name "BADNAME" could not be found. SQLSTATE=42705 SQLCODE=-1013

Vedere anche:

db2_conn_error()

db2_connect

(PECL)

db2_connect -- Returns a connection to a database

Descrizione

resource db2_connect ( string database, string username, string password [, array options] )

Creates a new connection to an IBM DB2 Universal Database, IBM Cloudscape, or Apache Derby database.

Elenco dei parametri

database

For a cataloged connection to a database, database represents the database alias in the DB2 client catalog.

For an uncataloged connection to a database, database represents a complete connection string in the following format: DRIVER={IBM DB2 ODBC DRIVER};DATABASE=database;HOSTNAME=hostname;PORT=port;PROTOCOL=TCPIP;UID=username;PWD=password; where the parameters represent the following values:

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 NULL value or empty string.

password

The password with which you are connecting to the database.

For uncataloged connections, you must pass a NULL value 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.

Valori restituiti

Returns a connection handle resource if the connection attempt is successful. If the connection attempt fails, db2_connect() returns FALSE.

Esempi

Esempio 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."; } ?>
Il precedente esempio visualizzerà:
Connection succeeded.

Esempio 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."; } ?>
Il precedente esempio visualizzerà:
Connection succeeded.

Esempio 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."; } ?>
Il precedente esempio visualizzerà:
Connection succeeded. Autocommit is off.

Vedere anche:

db2_close()

db2_pconnect()

db2_cursor_type

(PECL)

db2_cursor_type -- Returns the cursor type used by a statement resource

Descrizione

int db2_cursor_type ( resource 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.

Elenco dei parametri

stmt: A valid statement resource.

Valori restituiti

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.

Vedere anche:

db2_exec

(PECL)

db2_exec -- Executes an SQL statement directly

Descrizione

resource db2_exec ( resource connection, string statement [, array options] )

Prepares and executes an SQL statement.

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.

Elenco dei parametri

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.

cursor

Passing the DB2_FORWARD_ONLY value requests a forward-only cursor for this SQL statement. This is the default type of cursor, and it is supported by all database servers. It is also much faster than a scrollable cursor.

Passing the DB2_SCROLLABLE value requests a scrollable cursor for this SQL statement. This type of cursor enables you to fetch rows non-sequentially from the database server. However, it is only supported by DB2 servers, and is much slower than forward-only cursors.

Valori restituiti

Returns a statement resource if the SQL statement was issued successfully, or FALSE if the database failed to execute the SQL statement.

Esempi

Esempio 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... "; } } ?>
Il precedente esempio visualizzerà:
Successfully created the table. Insert... Insert... Insert... Insert... Insert... Insert... Insert...

Esempio 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"; } } ?>
Il precedente esempio visualizzerà:
Bubbles Gizmo Pook Rickety Ride

Vedere anche:

db2_execute

(PECL)

db2_execute -- Executes a prepared SQL statement

Descrizione

bool db2_execute ( resource 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().

Elenco dei parametri

stmt: A prepared statement returned from db2_prepare().
parameters: An array of input parameters matching any parameter markers contained in the prepared statement.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 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."; } } ?>
Il precedente esempio visualizzerà:
Successfully added new pet.

Esempio 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!"; ?>
Il precedente esempio visualizzerà:
I have 7 pets!

Vedere anche:

db2_exec()

db2_fetch_array

(PECL)

db2_fetch_array -- Returns an array, indexed by column position, representing a row in a result set

Descrizione

array db2_fetch_array ( resource stmt [, int row_number] )

Returns an array, indexed by column position, representing a row in a result set. The columns are 0-indexed.

Elenco dei parametri

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.

Valori restituiti

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.

Esempi

Esempio 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]); } ?>
Il precedente esempio visualizzerà:
0 Pook cat 3.20 5 Rickety Ride goat 9.70 2 Smarty horse 350.00

Esempio 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_array($result, $i)) { printf ("%-5d %-16s %-32s %10s\n", $row[0], $row[1], $row[2], $row[3]); $i = $i + 2; } ?>
Il precedente esempio visualizzerà:
0 Pook cat 3.20 5 Rickety Ride goat 9.70 2 Smarty horse 350.00

Vedere anche:

db2_fetch_assoc

(PECL)

db2_fetch_assoc -- Returns an array, indexed by column name, representing a row in a result set

Descrizione

array db2_fetch_assoc ( resource stmt [, int row_number] )

Returns an array, indexed by column name, representing a row in a result set.

Elenco dei parametri

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.

Valori restituiti

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.

Esempi

Esempio 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']); } ?>
Il precedente esempio visualizzerà:
0 Pook cat 3.20 5 Rickety Ride goat 9.70 2 Smarty horse 350.00

Esempio 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; } ?>
Il precedente esempio visualizzerà:
0 Pook cat 3.20 5 Rickety Ride goat 9.70 2 Smarty horse 350.00

Vedere anche:

db2_fetch_both

(PECL)

db2_fetch_both -- Returns an array, indexed by both column name and position, representing a row in a result set

Descrizione

array db2_fetch_both ( resource stmt [, int row_number] )

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().

Elenco dei parametri

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.

Valori restituiti

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.

Esempi

Esempio 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]); } ?>
Il precedente esempio visualizzerà:
0 Pook cat 3.20 5 Rickety Ride goat 9.70 2 Smarty horse 350.00

Esempio 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; } ?>
Il precedente esempio visualizzerà:
0 Pook cat 3.20 5 Rickety Ride goat 9.70 2 Smarty horse 350.00

Vedere anche:

db2_fetch_object

(PECL)

db2_fetch_object -- Returns an object with properties representing columns in the fetched row

Descrizione

object db2_fetch_object ( resource stmt [, int row_number] )

Returns an object in which each property represents a column returned in the row fetched from a result set.

Elenco dei parametri

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.

Valori restituiti

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.

Esempi

Esempio 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); } ?>
Il precedente esempio visualizzerà:
Come here, Pook, my little cat!

Vedere anche:

db2_fetch_row

(PECL)

db2_fetch_row -- Sets the result set pointer to the next row or requested row

Descrizione

bool db2_fetch_row ( resource 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.

Elenco dei parametri

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.

Valori restituiti

Returns TRUE if the requested row exists in the result set. Returns FALSE if the requested row does not exist in the result set.

Esempi

Esempio 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"; } ?>
Il precedente esempio visualizzerà:
cat Pook gold fish Bubbles budgerigar Gizmo goat Rickety Ride

Vedere anche:

db2_field_display_size

(PECL)

db2_field_display_size -- Returns the maximum number of bytes required to display a column

Descrizione

int db2_field_display_size ( resource stmt, mixed column )

Returns the maximum number of bytes required to display a column in a result set.

Elenco dei parametri

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.

Valori restituiti

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.

Vedere anche:

db2_field_name

(PECL)

db2_field_name -- Returns the name of the column in the result set

Descrizione

string db2_field_name ( resource stmt, mixed column )

Returns the name of the specified column in the result set.

Elenco dei parametri

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.

Valori restituiti

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.

Vedere anche:

db2_field_num

(PECL)

db2_field_num -- Returns the position of the named column in a result set

Descrizione

int db2_field_num ( resource stmt, mixed column )

Returns the position of the named column in a result set.

Elenco dei parametri

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.

Valori restituiti

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.

Vedere anche:

db2_field_precision

(PECL)

db2_field_precision -- Returns the precision of the indicated column in a result set

Descrizione

int db2_field_precision ( resource stmt, mixed column )

Returns the precision of the indicated column in a result set.

Elenco dei parametri

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.

Valori restituiti

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.

Vedere anche:

db2_field_scale

(PECL)

db2_field_scale -- Returns the scale of the indicated column in a result set

Descrizione

int db2_field_scale ( resource stmt, mixed column )

Returns the scale of the indicated column in a result set.

Elenco dei parametri

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.

Valori restituiti

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.

Vedere anche:

db2_field_type

(PECL)

db2_field_type -- Returns the data type of the indicated column in a result set

Descrizione

string db2_field_type ( resource stmt, mixed column )

Returns the data type of the indicated column in a result set.

Elenco dei parametri

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.

Valori restituiti

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.

Vedere anche:

db2_field_width

(PECL)

db2_field_width -- Returns the width of the current value of the indicated column in a result set

Descrizione

int db2_field_width ( resource stmt, mixed column )

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.

Elenco dei parametri

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.

Valori restituiti

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.

Vedere anche:

db2_foreign_keys

(PECL)

db2_foreign_keys -- Returns a result set listing the foreign keys for a table

Descrizione

resource db2_foreign_keys ( resource connection, string qualifier, string schema, string table-name )

Returns a result set listing the foreign keys for a table.

Elenco dei parametri

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 NULL or an empty string.
schema: The schema which contains the tables. If schema is NULL, db2_foreign_keys() matches the schema for the current connection.
table-name: The name of the table.

Valori restituiti

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.

Vedere anche:

db2_free_result

(PECL)

db2_free_result -- Frees resources associated with a result set

Descrizione

bool db2_free_result ( resource 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.

Elenco dei parametri

stmt: A valid statement resource.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

db2_free_stmt()

db2_free_stmt

(PECL)

db2_free_stmt -- Frees resources associated with the indicated statement resource

Descrizione

bool db2_free_stmt ( resource 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.

Elenco dei parametri

stmt: A valid statement resource.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

db2_free_result()

db2_next_result

(PECL)

db2_next_result -- Requests the next result set from a stored procedure

Descrizione

resource db2_next_result ( resource 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.

Elenco dei parametri

stmt: A prepared statement returned from db2_exec() or db2_execute().

Valori restituiti

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.

Esempi

Esempio 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); } ?>
Il precedente esempio visualizzerà:
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)

db2_num_fields -- Returns the number of fields contained in a result set

Descrizione

int db2_num_fields ( resource 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.

Elenco dei parametri

stmt: A valid statement resource containing a result set.

Valori restituiti

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.

Esempi

Esempio 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."; ?>
Il precedente esempio visualizzerà:
There are 4 columns in the result set.

Vedere anche:

db2_num_rows

(PECL)

db2_num_rows -- Returns the number of rows affected by an SQL statement

Descrizione

int db2_num_rows ( resource 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.

Nota: 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.

Elenco dei parametri

stmt: A valid stmt resource containing a result set.

Valori restituiti

Returns the number of rows affected by the last SQL statement issued by the specified statement handle.

db2_pconnect

(PECL)

db2_pconnect -- Returns a persistent connection to a database

Descrizione

resource db2_pconnect ( string 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 Capitolo 41.

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.

Note that you are strongly urged to only use persistent connections on connections with autocommit turned on. If you attempt to combine transactions with persistent connections, issuing db2_commit() or db2_rollback() against a persistent connection will affect every persistent connection that is currently using the same underlying DB2 client connection. You may also rapidly experience locking escalation if you do not use autocommit for your persistent connections.

Elenco dei parametri

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.

Valori restituiti

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.

Esempi

Esempio 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."; } ?>
Il precedente esempio visualizzerà:
Persistent connection succeeded. Second persistent connection succeeded.

Vedere anche:

db2_prepare

(PECL)

db2_prepare -- Prepares an SQL statement to be executed

Descrizione

resource db2_prepare ( resource 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().

Elenco dei parametri

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.

cursor

Valori restituiti

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().

Esempi

Vedere anche:

db2_bind_param()

db2_primary_keys

(PECL)

db2_primary_keys -- Returns a result set listing primary keys for a table

Descrizione

resource db2_primary_keys ( resource connection, string qualifier, string schema, string table-name )

Returns a result set listing the primary keys for a table.

Elenco dei parametri

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 NULL or an empty string.
schema: The schema which contains the tables. If schema is NULL, db2_primary_keys() matches the schema for the current connection.
table-name: The name of the table.

Valori restituiti

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.

Vedere anche:

db2_procedure_columns

(PECL)

db2_procedure_columns -- Returns a result set listing stored procedure parameters

Descrizione

resource db2_procedure_columns ( resource connection, string qualifier, string schema, string procedure, string parameter )

Returns a result set listing the parameters for one or more stored procedures.

Elenco dei parametri

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 NULL or 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.

Valori restituiti

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:

Return value	Parameter type
1 (SQL_PARAM_INPUT)	Input (IN) parameter.
2 (SQL_PARAM_INPUT_OUTPUT)	Input/output (INOUT) parameter.
3 (SQL_PARAM_OUTPUT)	Output (OUT) 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.

Vedere anche:

db2_procedures

(PECL)

db2_procedures -- Returns a result set listing the stored procedures registered in a database

Descrizione

resource db2_procedures ( resource connection, string qualifier, string schema, string procedure )

Returns a result set listing the stored procedures registered in a database.

Elenco dei parametri

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 NULL or 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.

Valori restituiti

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.

Vedere anche:

db2_result

(PECL)

db2_result -- Returns a single column from a row in the result set

Descrizione

mixed db2_result ( resource stmt, mixed column )

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.

Elenco dei parametri

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.

Valori restituiti

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.

Esempi

Esempio 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"; } ?>
Il precedente esempio visualizzerà:
cat Pook gold fish Bubbles budgerigar Gizmo goat Rickety Ride

Vedere anche:

db2_rollback

(PECL)

db2_rollback -- Rolls back a transaction

Descrizione

bool db2_rollback ( resource 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.

Nota: If the specified connection resource is a persistent connection, all transactions in progress for all applications using that persistent connection will be rolled back. For this reason, persistent connections are not recommended for use in applications that require transactions.

Elenco dei parametri

connection: A valid database connection resource variable as returned from db2_connect() or db2_pconnect().

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 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); } ?>
Il precedente esempio visualizzerà:
7 0 7

Vedere anche:

db2_autocommit()

db2_commit()

db2_server_info

(no version information, might be only in CVS)

db2_server_info -- Returns an object with properties that describe the DB2 database server

Descrizione

object db2_server_info ( resource 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:

Tabella 1. 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: UR Uncommitted read: changes are immediately visible by all concurrent transactions. CS Cursor stability: a row read by one transaction can be altered and committed by a second concurrent transaction. RS Read stability: a transaction can add or remove rows matching a search condition or a pending transaction. RR Repeatable read: data affected by pending transaction is not available to other transactions. NC No commit: any changes are visible at the end of a successful operation. Explicit commits and rollbacks are not allowed.
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: ENTRY Entry-level SQL-92 compliance. FIPS127 FIPS-127-2 transitional compliance. FULL Full level SQL-92 compliance. INTERMEDIATE Intermediate level SQL-92 compliance.

Elenco dei parametri

connection: Specifies an active DB2 client connection.

Valori restituiti

Returns an object on a successful call. Returns FALSE on failure.

Esempi

Esempio 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); } ?>
Il precedente esempio visualizzerà:
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)

Vedere anche:

db2_client_info()

db2_special_columns

(PECL)

db2_special_columns -- Returns a result set listing the unique row identifier columns for a table

Descrizione

resource db2_special_columns ( resource connection, string qualifier, string schema, string table_name, int scope )

Returns a result set listing the unique row identifier columns for a table.

Elenco dei parametri

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 NULL or 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.

Valori restituiti

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

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.

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.

PSEUDO_COLUMN Always returns 1.

Vedere anche:

db2_statistics

(PECL)

db2_statistics -- Returns a result set listing the index and statistics for a table

Descrizione

resource db2_statistics ( resource connection, string qualifier, string schema, string table-name, bool unique )

Returns a result set listing the index and statistics for a table.

Elenco dei parametri

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 NULL or 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.

Valori restituiti

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:

Return value	Parameter type
0 (SQL_FALSE)	The index allows duplicate values.
1 (SQL_TRUE)	The index values must be unique.
`NULL`	This row is statistics information for 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:

Return value	Parameter type
0 (SQL_TABLE_STAT)	The row contains statistics about the table itself.
1 (SQL_INDEX_CLUSTERED)	The row contains information about a clustered index.
2 (SQL_INDEX_HASH)	The row contains information about a hashed index.
3 (SQL_INDEX_OTHER)	The row contains information about a type of index that is neither clustered nor hashed.

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.

Vedere anche:

db2_stmt_error

(PECL)

db2_stmt_error -- Returns a string containing the SQLSTATE returned by an SQL statement

Descrizione

string db2_stmt_error ( [resource 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 '? sqlstate-value'. You can also call db2_stmt_errormsg() to retrieve an explicit error message and the associated SQLCODE value.

Elenco dei parametri

stmt: A valid statement resource.

Valori restituiti

Returns a string containing an SQLSTATE value.

Vedere anche:

db2_conn_error()

db2_conn_errormsg()

db2_stmt_errormsg

(PECL)

db2_stmt_errormsg -- Returns a string containing the last SQL statement error message

Descrizione

string db2_stmt_errormsg ( [resource 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().

Elenco dei parametri

stmt: A valid statement resource.

Valori restituiti

Returns a string containing the error message and SQLCODE value for the last error that occurred issuing an SQL statement.

Vedere anche:

db2_conn_error()

db2_conn_errormsg()

db2_table_privileges

(PECL)

db2_table_privileges -- Returns a result set listing the tables and associated privileges in a database

Descrizione

resource db2_table_privileges ( resource connection [, string qualifier [, string schema [, string table_name]]] )

Returns a result set listing the tables and associated privileges in a database.

Elenco dei parametri

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 NULL or 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.

Valori restituiti

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.

Vedere anche:

db2_tables

(PECL)

db2_tables -- Returns a result set listing the tables and associated metadata in a database

Descrizione

resource db2_tables ( resource connection [, string qualifier [, string schema [, string table-name [, string table-type]]]] )

Returns a result set listing the tables and associated metadata in a database.

Elenco dei parametri

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 NULL or 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 NULL or 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.

Valori restituiti

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.

Vedere anche:

maxdb_fetch_field(), maxdb_field_seek()

LII. ICAP Functions [deprecated]

Introduzione

Nota: Icap will be removed in near future. Neither this module, nor those versions of icap library are supported any longer. If you want to use calendar capabilities in PHP, use mcal instead.

Requisiti

The icap library has to be installed, which is not longer supported and available.

Installazione

To get these functions to work, you have to compile PHP with --with-icap.

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

Questa estensione non definisce alcuna costante.

Sommario
icap_close -- Close an ICAP stream
icap_create_calendar -- Create a new calendar
icap_delete_calendar -- Delete a calendar
icap_delete_event -- Delete an event from an ICAP calendar
icap_fetch_event -- Fetches an event from the calendar stream/
icap_list_alarms -- Return a list of events that has an alarm triggered at the given datetime
icap_list_events -- Return a list of events between two given datetimes
icap_open -- Opens up an ICAP connection
icap_rename_calendar -- Rename a calendar
icap_reopen -- Reopen ICAP stream to new calendar
icap_snooze -- Snooze an alarm
icap_store_event -- Store an event into an ICAP calendar

icap_close

(no version information, might be only in CVS)

icap_close -- Close an ICAP stream

int icap_fetch_event ( int stream_id, int event_id [, int options] )

icap_fetch_event() fetches an event from the calendar stream specified by event_id.

Returns an event object consisting of:

int id - ID of that event.
int public - TRUE if the event if public, FALSE if it is private.
string category - Category string of the event.
string title - Title string of the event.
string description - Description string of the event.
int alarm - number of minutes before the event to send an alarm/reminder.
object start - Object containing a datetime entry.
object end - Object containing a datetime entry.

All datetime entries consist of an object that contains:

int year - year
int month - month
int mday - day of month
int hour - hour
int min - minutes
int sec - seconds

icap_list_alarms

(PHP 4 <= 4.2.3)

icap_list_alarms -- Return a list of events that has an alarm triggered at the given datetime

Description

int icap_list_alarms ( int stream_id, array date, array time )

Returns an array of event ID's that has an alarm going off at the given datetime.

icap_list_alarms() function takes in a datetime for a calendar stream. An array of event id's that has an alarm should be going off at the datetime are returned.

All datetime entries consist of an object that contains:

int year - year
int month - month
int mday - day of month
int hour - hour
int min - minutes
int sec - seconds

icap_list_events

(PHP 4 <= 4.2.3)

icap_list_events -- Return a list of events between two given datetimes

Description

array icap_list_events ( int stream_id, int begin_date [, int end_date] )

Returns an array of event ID's that are between the two given datetimes.

icap_list_events() function takes in a beginning datetime and an end datetime for a calendar stream. An array of event id's that are between the given datetimes are returned.

All datetime entries consist of an object that contains:

int year - year
int month - month
int mday - day of month
int hour - hour
int min - minutes
int sec - seconds

All datetime entries consist of an object that contains:

int year - year
int month - month
int mday - day of month
int hour - hour
int min - minutes
int sec - seconds

Returns TRUE on success and FALSE on error.

LIII. Iconv

Introduzione

Questo modulo contiene un'interfaccia al tool di conversione dei caratteri iconv. Tramite questo modulo si può convertire una stringa dal set di caratteri locale ad un'altro. I set di caratteri supportati dipendono dalla implementazione di iconv installata. Occorre rilevare che le funzioni iconv, in alcuni sistemi, possono non fornire le risposte attese. In questi casi è una buona idea installarela libreria GNU libiconv, la quale fornisce risultati più consistenti.

Dalla versione 5.0.0 di PHP, questa versione viene rilasciata con diverse funzioni che aiutano a realizzare script in più lingue. Guardare nelle sezioni seguenti per scoprire queste nuove caratteristiche.

Requisiti

Non occorre nulla se il sistema che si sta utilizzando è un sistema recente compatibile POSIX, poichè le librerie C standard fornite con la macchina forniscono le funzioni iconv. Negli altri casi occorre installare sul sistema la libreria libiconv

Installazione

Per potere utilizzare le funzioni fornite da questo modulo, occorre compila il PHP con la seguente linea di configurazione: --with-iconv[=DIR].

Note per gli utenti Windows®: Per potere abilitare questo modulo nei sistemi Windows® occorre posizionare la DLL iconv.dll o iconv-1.3.dll (nelle versioni precedenti alla 4.2.1), rilasciata con il pacchetto PHP/Win32 nella directory indicata dalla variabile d'ambiente PATH oppure in una directory di installazione di Windows®.

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

Tabella 1. Parametri di configurazione di Iconv

Nome	Default	Modificabile
iconv.input_encoding	ICONV_INPUT_ENCODING	PHP_INI_ALL
iconv.output_encoding	ICONV_OUTPUT_ENCODING	PHP_INI_ALL
iconv.internal_encoding	ICONV_INTERNAL_ENCODING	PHP_INI_ALL

Per maggiori dettagli e definizioni delle costanti PHP_INI_* vedere ini_set().

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

Dalla versione 4.3.0 di PHP è possibile identificare da untime quale implementazione di iconv è adottata da questo modulo.

Tabella 2. Costanti iconv

Nome	Tipo	Descrizione
ICONV_IMPL	string	Il nome dell'implementazione
ICONV_VERSION	string	Versione dell'implementazione

Nota: La scrittura di codice che utilizzi tali costanti per identificare l'implementazione è scoraggiata.

Dalla versione 5.0.0 di PHP saranno disponibili le seguenti costanti:

Tabella 3. Costanti iconv dispèonibili da PHP 5.0.0

Nome	Tipo	Descrizione
ICONV_MIME_DECODE_STRICT	integer	Maschera di bit utilizzata da iconv_mime_decode()
ICONV_MIME_DECODE_CONTINUE_ON_ERROR	integer	Maschera di bit utilizzata per iconv_mime_decode()

Vedere anche:

Vedere anche GNU Recode.

Sommario
iconv_get_encoding -- Visualizza l'attuale impostazione per la conversione dei caratteri codificati
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 -- Setta l'attuale impostazione per la conversione dei caratteri codificati
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 the specified range of haystack
iconv_substr -- Cut out part of a string
iconv -- Converte una stringa nel set di caratteri richiesto
ob_iconv_handler -- Converte caratteri codificati come un output buffer handler

iconv_get_encoding

(PHP 4 >= 4.0.5, PHP 5)

iconv_get_encoding -- Visualizza l'attuale impostazione per la conversione dei caratteri codificati

Descrizione

array iconv_get_encoding ( [string type] )

Restituisce l'attuale impostazione di ob_iconv_handler() come array o FALSE in caso di insuccesso.

Vedere anche: iconv_set_encoding() e ob_iconv_handler().

iconv_mime_decode_headers

(PHP 5)

iconv_mime_decode_headers -- Decodes multiple MIME header fields at once

Description

array iconv_mime_decode_headers ( string encoded_headers [, int mode [, string charset]] )

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.

mode determines the behaviour in the event iconv_mime_decode_headers() encounters a malformed MIME header field. You can specify any combination of the following bitmasks.

Tabella 1. 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.

The optional charset parameter specifies the character set to represent the result by. If omitted, iconv.internal_charset will be used.

Esempio 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);
?>

Il precedente esempio visualizzerà:

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
        )

)

iconv_mime_decode

(PHP 5)

iconv_mime_decode -- Decodes a MIME header field

Description

string iconv_mime_decode ( string encoded_header [, int mode [, string charset]] )

Returns a decoded MIME field on success, or FALSE if an error occurs during the decoding.

mode determines the behaviour in the event iconv_mime_decode() encounters a malformed MIME header field. You can specify any combination of the following bitmasks.

Tabella 1. 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() attempts to continue to process the given header even though an error occurs.

The optional charset parameter specifies the character set to represent the result by. If omitted, iconv.internal_charset will be used.

Esempio 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");
?>

iconv_mime_encode

(PHP 5)

iconv_mime_encode -- Composes a MIME header field

Description

string iconv_mime_encode ( string field_name, string field_value [, array preferences] )

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
In the above example, "Subject" is the field name and the portion that begins with "=?ISO-8859-1?..." is the field value.

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.

Tabella 1. Configuration items supported by iconv_mime_encode()

Item	Type	Description	Default value	Example
scheme	boolean	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_name` and the second parameter `field_value` are presented. If not given, iconv_mime_encode() assumes those parameters are presented to it in the iconv.internal_charset ini setting.	iconv.internal_charset	ISO-8859-1
output-charset	string	Specifies the character set to use to compose the `MIME` header. If not given, the same value as `input-charset` will be used.	the same value as `input-charset`	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

Esempio 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_Pr=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);
?>

iconv_set_encoding

(PHP 4 >= 4.0.5, PHP 5)

iconv_set_encoding -- Setta l'attuale impostazione per la conversione dei caratteri codificati

Descrizione

iconv_strrpos -- Finds the last occurrence of a needle within the specified range of haystack

Description

int iconv_strrpos ( string haystack, string needle [, string charset] )

Returns the numeric position of the last occurrence of needle in haystack.

If needle is not found, iconv_strrpos() will return FALSE.

Avvertimento

If haystack or needle is not a string, it is converted to a string and applied as the ordinal value of a character.

In contrast to strpos(), 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.

iconv_substr

(PHP 5)

iconv_substr -- Cut out part of a string

Description

string iconv_substr ( string str, int offset [, int length [, string charset]] )

Returns the portion of str specified by the start and length parameters.

If start is non-negative, iconv_substr() cuts the portion out of str beginning at start'th character, counting from zero.

If start is negative, iconv_substr() cuts out the portion beginning at the position, start characters away from the end of str.

If length is given and is positive, the return value will contain at most length characters of the portion that begins at start (depending on the length of string). If str is shorter than start characters long, FALSE will be returned.

If negative length is passed, iconv_substr() cuts the portion out of str from the start'th character up to the character that is length characters away from the end of the string. In case start is also negative, the start position is calculated beforehand according to the rule explained above.

Note that offset and length parameters are always deemed to represent offsets that are calculated on the basis of the character set determined by charset, whilst the counterpart substr() always takes these for byte offsets. If charset is not given, the character set is determined by the iconv.internal_encoding ini setting.

iconv

(PHP 4 >= 4.0.5, PHP 5)

iconv -- Converte una stringa nel set di caratteri richiesto

Descrizione

string iconv ( string in_charset, string out_charset, string str )

Converte la stringa codificata nel parametro stringa in in_charset nella stringa codificata in out_charset. Restituisce la stringa convertita o FALSE, se fallisce.

Esempio 1. Esempio di iconv():
echo iconv("ISO-8859-1","UTF-8","This is test.");

ob_iconv_handler

(PHP 4 >= 4.0.5, PHP 5)

ob_iconv_handler -- Converte caratteri codificati come un output buffer handler

Descrizione

array ob_iconv_handler ( string contents, int status )

Converte la stringa codificata del parametro internal_encoding in output_encoding.

internal_encoding e output_encoding dovrebbero essere definite da iconv_set_encoding() o nel file di configurazione.

Esempio 1. Esempio di ob_iconv_handler():
ob_start("ob_iconv_handler"); // start output buffering

Vedere anche: iconv_get_encoding() e iconv_set_encoding().

LIV. ID3 Functions

Introduzione

These functions let you read and manipulate ID3 tags. ID3 tags are used in MP3 files to store title of the song, as well as information about the artist, album, genre, year and track number.

Since version 0.2 it is also possible to extract text frames from ID3 v2.2+ tags.

Requisiti

Non sono necessarie librerie esterne per utilizzare questo modulo.

Installazione

id3 is part of PECL and can be installed using the PEAR installer. To compile PHP with id3 support, download the sourcecode, put it in php-src/ext/id3 and compile PHP using --enable-id3.

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

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_0 is 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_1 is 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_1 is used if you are working with ID3 V2.1 tags.
ID3_V2_2 (integer): ID3_V2_2 is used if you are working with ID3 V2.2 tags.
ID3_V2_3 (integer): ID3_V2_3 is used if you are working with ID3 V2.3 tags.
ID3_V2_4 (integer): ID3_V2_4 is used if you are working with ID3 V2.4 tags.
ID3_BEST (integer): ID3_BEST is used if would like to let the id3 functions determine which tag version should be used.

Sommario
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

id3_get_frame_long_name

(PECL)

id3_get_frame_long_name -- Get the long name of an ID3v2 frame

array id3_get_tag ( string filename [, int version] )

id3_get_tag() is used to get all information stored in the id3 tag of the specified file.

Nota: Instead of a filename you may also pass a valid stream resource.

The optional version parameter allows you to specify the version of the tag as MP3 files may contain both, version 1.x and version 2.x tags.

Esempio 1. id3_get_tag() example
<?php $tag = id3_get_tag( "path/to/example.mp3" ); print_r($tag); ?>
This will output something like:
Array ( [title] => DN-38416 [artist] => Re:\Legion [album] => Reflections [year] => 2004 [genre] => 19 )

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.

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.

Esempio 2. id3_get_tag() example
<?php $tag = id3_get_tag( "path/to/example2.mp3", ID3_V2_3 ); print_r($tag); ?>
This will output something like:
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 )

ID3 v2.x tags can contain a lot more information about the MP3 file than ID3 v1.x tags.

id3_get_version

(PECL)

id3_get_version -- Get version of an ID3 tag

Description

int id3_get_version ( string filename )

id3_get_version() retrieves the version(s) of the ID3 tag(s) in the MP3 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.

Nota: Instead of a filename you may also pass a valid stream resource.

Esempio 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"; } ?>
This will output something like:
Contains a 1.x tag Contains a 1.1 tag

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.

id3_remove_tag

(PECL)

id3_remove_tag -- Remove an existing ID3 tag

Description

bool id3_remove_tag ( string filename [, int version] )

id3_remove_tag() is used to remove the information stored of an ID3 tag. If no tag has been present, it will return FALSE and leave the file as it was.

Nota: Instead of a filename you may also pass a valid stream resource.

The optional version parameter allows you to specify the version of the tag as MP3 files may contain both, version 1.x and version 2.x tags.

Esempio 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

Nota: 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.

id3_set_tag

(PECL)

id3_set_tag -- Update information stored in an ID3 tag

Description

bool id3_set_tag ( string filename, array tag [, int version] )

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.

Nota: Instead of a filename you may also pass a valid stream resource.

The optional version parameter allows you to specify the version of the tag as MP3 files may contain both, version 1.x and version 2.x tags.

Esempio 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

Nota: Currently id3_set_tag() only supports version 1.0 and 1.1.

The following keys may be used in the associative array:

Tabella 1. 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

LV. Funzioni di Amministrazione IIS

Introduzione

This PECL extension is not bundled with PHP. Questa estensione è disponibile solo per sistemi Win32. Prevede funzioni per amministrare Microsoft Internet Information Server (IIS). L'estensione include la funzione per creare siti web e directory virtuali come meglio e come la configurazione della sicurezza e lo script mapping. Queste funzioni sono state aggiunte nel PHP 4.

Per potere utilizzare queste funzioni occorre abilitare l'uso della dll php_iisfunc.dll dal php.ini. You may download this PECL extension DLL from the PHP Downloads page or at http://snaps.php.net/.

Requisiti

Non sono necessarie librerie esterne per utilizzare questo modulo.

Installazione

Non è necessaria nessuna installazione per usare queste funzioni, esse fanno parte del core di PHP.

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

Questa estensione non definisce alcuna costante.

Sommario
iis_add_server -- Crea un nuovo web server virtuale
iis_get_dir_security -- Riceve informazioni sulla sicurezza della cartella
iis_get_script_map -- Riceve informazioni sul mapping dello script sulla cartella virtuale per una specifica estensioneo
iis_get_server_by_comment -- Restituisce il numero d'istanza associato con il commento
iis_get_server_by_path -- Restituisce il numero di istanza associato alla Path
iis_get_server_rights -- Riceve informaizoni sui diritti del server
iis_get_service_state -- Avvia il servizio definito da service_id
iis_remove_server -- Rimuove il web server virtuale indicato da Server_instance
iis_set_app_settings -- Crea application scope per una cartella virtuale
iis_set_dir_security -- Imposta la sicurezza nella cartella
iis_set_script_map -- Imposta il mapping dello script sulla cartella virtuale
iis_set_server_rights -- Imposta i diritti del server
iis_start_server -- Avvia il web server virtuale
iis_start_service -- Avvia il servizio definito da service_id
iis_stop_server -- Ferma il web server virtuale
iis_stop_service -- Ferma il servizio definito da service_id

Se hai installato le librerie GD (scaricabili su http://www.boutell.com/gd/) sarai anche in grado di creare immagini al volo e di modificarle.

I formati delle immagini sulle quali potrai agire dipendono dalla versione delle librerie GD che hai installato, e dalle altre librerie di cui GD può aver bisogno per accedere a quei formati di immagine. Versioni precedenti alla gd-1.6 supportano il formato GIF ma non quello PNG, mentre versioni superiori alla gd-1.6 supportano il formato PNG ma non il GIF.

Se hai compilato PHP con l'opzione --enable-exif sarai in grado di lavorare con le informazioni memorizzate negli header delle immagini JPEG e TIFF. Queste funzioni non richiedono le librerie GD.

Installazione

Per leggere e scrivere immagini in formato JPEG avrai bisogno di installare jpeg-6b (scaricabile da ftp://ftp.uu.net/graphics/jpeg/) e quindi ricompilare le librerie GD in modo che usino jpeg-6b. Dovrai anche compilare PHP con l'opzione --with-jpeg-dir=/percorso/per/jpeg-6b.

Per aggiungere il supporto per i Font Type 1 dovrai installare t1lib (scaricabile su ftp://sunsite.unc.edu/pub/Linux/libs/graphics/), e quindi aggiungere l'opzione --with-t1lib[=dir].

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

IMG_GIF (integer)
IMG_JPG (integer)
IMG_JPEG (integer)
IMG_PNG (integer)
IMG_WBMP (integer)
IMG_XPM (integer)
IMG_COLOR_TILED (integer)
IMG_COLOR_STYLED (integer)
IMG_COLOR_BRUSHED (integer)
IMG_COLOR_STYLEDBRUSHED (integer)
IMG_COLOR_TRANSPARENT (integer)
IMG_ARC_ROUNDED (integer)
IMG_ARC_PIE (integer)
IMG_ARC_CHORD (integer)
IMG_ARC_NOFILL (integer)
IMG_ARC_EDGED (integer)
IMAGETYPE_GIF (integer)
IMAGETYPE_JPEG (integer)
IMAGETYPE_PNG (integer)
IMAGETYPE_SWF (integer)
IMAGETYPE_PSD (integer)
IMAGETYPE_BMP (integer)
IMAGETYPE_WBMP (integer)
IMAGETYPE_XBM (integer)
IMAGETYPE_TIFF_II (integer)
IMAGETYPE_TIFF_MM (integer)
IMAGETYPE_IFF (integer)
IMAGETYPE_JB2 (integer)
IMAGETYPE_JPC (integer)
IMAGETYPE_JP2 (integer)
IMAGETYPE_JPX (integer)
IMAGETYPE_SWC (integer)

Sommario
gd_info -- Retrieve information about the currently installed GD library
getimagesize -- Get the size of an image
image_type_to_extension -- Get file extension for image type
image_type_to_mime_type -- Get Mime-Type for image-type returned by getimagesize, exif_read_data, exif_thumbnail, exif_imagetype
image2wbmp -- Rende disponibile l'immagine per il browser o la salva in un file
imagealphablending -- Set the blending mode for an image
imageantialias -- Should antialias functions be used or not
imagearc -- Draw a partial ellipse
imagechar -- Draw a character horizontally
imagecharup -- Draw a character vertically
imagecolorallocate -- Allocate a color for an image
imagecolorallocatealpha -- Allocate a color for an image
imagecolorat -- Get the index of the color of a pixel
imagecolorclosest -- Get the index of the closest color to the specified color
imagecolorclosestalpha -- Get the index of the closest color to the specified color + alpha
imagecolorclosesthwb -- Get the index of the color which has the hue, white and blackness nearest to the given color
imagecolordeallocate -- De-allocate a color for an image
imagecolorexact -- Get the index of the specified color
imagecolorexactalpha -- Get the index of the specified color + alpha
imagecolormatch -- Makes the colors of the palette version of an image more closely match the true color version
imagecolorresolve -- Get the index of the specified color or its closest possible alternative
imagecolorresolvealpha -- Get the index of the specified color + alpha or its closest possible alternative
imagecolorset -- Set the color for the specified palette index
imagecolorsforindex -- Get the colors for an index
imagecolorstotal -- Find out the number of colors in an image's palette
imagecolortransparent -- Define a color as transparent
imageconvolution -- Apply a 3x3 convolution matrix, using coefficient div and offset
imagecopy -- Copy part of an image
imagecopymerge -- Copy and merge part of an image
imagecopymergegray -- Copy and merge part of an image with gray scale
imagecopyresampled -- Copy and resize part of an image with resampling
imagecopyresized -- Copy and resize part of an image
imagecreate -- Create a new palette based image
imagecreatefromgd2 -- Create a new image from GD2 file or URL
imagecreatefromgd2part -- Create a new image from a given part of GD2 file or URL
imagecreatefromgd -- Create a new image from GD file or URL
imagecreatefromgif -- Create a new image from file or URL
imagecreatefromjpeg -- Create a new image from file or URL
imagecreatefrompng -- Create a new image from file or URL
imagecreatefromstring -- Create a new image from the image stream in the string
imagecreatefromwbmp -- Create a new image from file or URL
imagecreatefromxbm -- Create a new image from file or URL
imagecreatefromxpm -- Create a new image from file or URL
imagecreatetruecolor -- Create a new true color image
imagedashedline -- Draw a dashed line
imagedestroy -- Destroy an image
imageellipse -- Draw an ellipse
imagefill -- Flood fill
imagefilledarc -- Draw a partial ellipse and fill it
imagefilledellipse -- Draw a filled ellipse
imagefilledpolygon -- Draw a filled polygon
imagefilledrectangle -- Draw a filled rectangle
imagefilltoborder -- Flood fill to specific color
imagefilter -- Applies a filter to an image
imagefontheight -- Get font height
imagefontwidth -- Get font width
imageftbbox -- Give the bounding box of a text using fonts via freetype2
imagefttext -- Write text to the image using fonts using FreeType 2
imagegammacorrect -- Apply a gamma correction to a GD image
imagegd2 -- Output GD2 image to browser or file
imagegd -- Output GD image to browser or file
imagegif -- Output image to browser or file
imageinterlace -- Enable or disable interlace
imageistruecolor -- Finds whether an image is a truecolor image
imagejpeg -- Output image to browser or file
imagelayereffect -- Set the alpha blending flag to use the bundled libgd layering effects
imageline -- Draw a line
imageloadfont -- Load a new font
imagepalettecopy -- Copy the palette from one image to another
imagepng -- Output a PNG image to either the browser or a file
imagepolygon -- Draw a polygon
imagepsbbox -- Give the bounding box of a text rectangle using PostScript Type1 fonts
imagepscopyfont -- Make a copy of an already loaded font for further modification
imagepsencodefont -- Change the character encoding vector of a font
imagepsextendfont -- Extend or condense a font
imagepsfreefont -- Free memory used by a PostScript Type 1 font
imagepsloadfont -- Load a PostScript Type 1 font from file
imagepsslantfont -- Slant a font
imagepstext -- To draw a text string over an image using PostScript Type1 fonts
imagerectangle -- Draw a rectangle
imagerotate -- Rotate an image with a given angle
imagesavealpha -- Set the flag to save full alpha channel information (as opposed to single-color transparency) when saving PNG images
imagesetbrush -- Set the brush image for line drawing
imagesetpixel -- Set a single pixel
imagesetstyle -- Set the style for line drawing
imagesetthickness -- Set the thickness for line drawing
imagesettile -- Set the tile image for filling
imagestring -- Draw a string horizontally
imagestringup -- Draw a string vertically
imagesx -- Get image width
imagesy -- Get image height
imagetruecolortopalette -- Convert a true color image to a palette image
imagettfbbox -- Give the bounding box of a text using TrueType fonts
imagettftext -- Write text to the image using TrueType fonts
imagetypes -- Return the image types supported by this PHP build
imagewbmp -- Output image to browser or file
imagexbm -- Output XBM image to browser or file
iptcembed -- Embed binary IPTC data into a JPEG image
iptcparse -- Parse a binary IPTC http://www.iptc.org/ block into single tags.
jpeg2wbmp -- Convert JPEG image file to WBMP image file
png2wbmp -- Convert PNG image file to WBMP image file

gd_info

(PHP 4 >= 4.3.0, PHP 5)

gd_info -- Retrieve information about the currently installed GD library

Description

array gd_info ( void )

Returns an associative array describing the version and capabilities of the installed GD library.

Tabella 1. Elements of array returned by gd_info()

Attribute	Meaning
GD Version	string value describing the installed `libgd` version.
Freetype Support	boolean value. `TRUE` if Freetype Support is installed.
Freetype Linkage	string value describing the way in which Freetype was linked. Expected values are: 'with freetype', 'with TTF library', and 'with unknown library'. This element will only be defined if `Freetype Support` evaluated to `TRUE`.
T1Lib Support	boolean value. `TRUE` if `T1Lib` support is included.
GIF Read Support	boolean value. `TRUE` if support for reading `GIF` images is included.
GIF Create Support	boolean value. `TRUE` if support for creating `GIF` images is included.
JPG Support	boolean value. `TRUE` if `JPG` support is included.
PNG Support	boolean value. `TRUE` if `PNG` support is included.
WBMP Support	boolean value. `TRUE` if `WBMP` support is included.
XBM Support	boolean value. `TRUE` if `XBM` support is included.

Esempio 1. Using gd_info()
<?php var_dump(gd_info()); ?>
The typical output is :
array(9) { ["GD Version"]=> string(24) "bundled (2.0 compatible)" ["FreeType Support"]=> bool(false) ["T1Lib Support"]=> bool(false) ["GIF Read Support"]=> bool(true) ["GIF Create Support"]=> bool(false) ["JPG Support"]=> bool(false) ["PNG Support"]=> bool(true) ["WBMP Support"]=> bool(true) ["XBM Support"]=> bool(false) }

getimagesize

(PHP 3, PHP 4, PHP 5)

getimagesize -- Get the size of an image

Description

array getimagesize ( string filename [, array &imageinfo] )

The getimagesize() function will determine the size of any GIF, JPG, PNG, SWF, SWC, PSD, TIFF, BMP, IFF, JP2, JPX, JB2, JPC, XBM, or WBMP image file and return the dimensions along with the file type and a height/width text string to be used inside a normal HTML <IMG> tag.

If accessing the filename image is impossible, or if it isn't a valid picture, getimagesize() will return FALSE and generate an error of level E_WARNING.

Nota: Support for JPC, JP2, JPX, JB2, XBM, and WBMP became available in PHP 4.3.2. Support for SWC exists as of PHP 4.3.0 and TIFF support was added in PHP 4.2.0

Nota: JPEG 2000 support was added in PHP 4.3.2. Note that JPC and JP2 are capable of having components with different bit depths. In this case, the value for "bits" is the highest bit depth encountered. Also, JP2 files may contain multiple JPEG 2000 codestreams. In this case, getimagesize() returns the values for the first codestream it encounters in the root of the file.

Nota: The getimagesize() function does not require the GD image library.

Returns an array with 4 elements. Index 0 contains the width of the image in pixels. Index 1 contains the height. Index 2 is a flag indicating the type of the image: 1 = GIF, 2 = JPG, 3 = PNG, 4 = SWF, 5 = PSD, 6 = BMP, 7 = TIFF(intel byte order), 8 = TIFF(motorola byte order), 9 = JPC, 10 = JP2, 11 = JPX, 12 = JB2, 13 = SWC, 14 = IFF, 15 = WBMP, 16 = XBM. These values correspond to the IMAGETYPE constants that were added in PHP 4.3.0. Index 3 is a text string with the correct height="yyy" width="xxx" string that can be used directly in an IMG tag.
Esempio 1. getimagesize (file)
<?php list($width, $height, $type, $attr) = getimagesize("img/flag.jpg"); echo "<img src=\"img/flag.jpg\" $attr alt=\"getimagesize() example\" />"; ?>

URL support was added in PHP 4.0.5
Esempio 2. getimagesize (URL)
<?php $size = getimagesize("http://www.example.com/gifs/logo.gif"); // if the file name has space in it, encode it properly $size = getimagesize("http://www.example.com/gifs/lo%20go.gif"); ?>

With JPG images, two extra indexes are returned: channels and bits. channels will be 3 for RGB pictures and 4 for CMYK pictures. bits is the number of bits for each color.

Beginning with PHP 4.3.0, bits and channels are present for other image types, too. However, the presence of these values can be a bit confusing. As an example, GIF always uses 3 channels per pixel, but the number of bits per pixel cannot be calculated for an animated GIF with a global color table.

Some formats may contain no image or may contain multiple images. In these cases, getimagesize() might not be able to properly determine the image size. getimagesize() will return zero for width and height in these cases.

Beginning with PHP 4.3.0, getimagesize() also returns an additional parameter, mime, that corresponds with the MIME type of the image. This information can be used to deliver images with correct HTTP Content-type headers:
Esempio 3. getimagesize() and MIME types
<?php $size = getimagesize($filename); $fp=fopen($filename, "rb"); if ($size && $fp) { header("Content-type: {$size['mime']}"); fpassthru($fp); exit; } else { // error } ?>

The optional imageinfo parameter allows you to extract some extended information from the image file. Currently, this will return the different JPG APP markers as an associative array. Some programs use these APP markers to embed text information in images. A very common one is to embed IPTC http://www.iptc.org/ information in the APP13 marker. You can use the iptcparse() function to parse the binary APP13 marker into something readable.

Esempio 4. getimagesize() returning IPTC
<?php $size = getimagesize("testimg.jpg", $info); if (isset($info["APP13"])) { $iptc = iptcparse($info["APP13"]); var_dump($iptc); } ?>

image_type_to_extension

(no version information, might be only in CVS)

image_type_to_extension -- Get file extension for image type

Description

string image_type_to_extension ( int imagetype [, bool include_dot] )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

image_type_to_mime_type

(PHP 4 >= 4.3.0, PHP 5)

image_type_to_mime_type -- Get Mime-Type for image-type returned by getimagesize, exif_read_data, exif_thumbnail, exif_imagetype

Description

string image_type_to_mime_type ( int imagetype )

The image_type_to_mime_type() function will determine the Mime-Type for an IMAGETYPE constant.
Esempio 1. image_type_to_mime_type (file)
<?php header("Content-type: " . image_type_to_mime_type(IMAGETYPE_PNG)); ?>

The returned values are as follows

Tabella 1. Returned values Constants

`imagetype`	Returned value
`IMAGETYPE_GIF`	`image/gif`
`IMAGETYPE_JPEG`	`image/jpeg`
`IMAGETYPE_PNG`	`image/png`
`IMAGETYPE_SWF`	`application/x-shockwave-flash`
`IMAGETYPE_PSD`	`image/psd`
`IMAGETYPE_BMP`	`image/bmp`
`IMAGETYPE_TIFF_II` (intel byte order)	`image/tiff`
`IMAGETYPE_TIFF_MM` (motorola byte order)	`image/tiff`
`IMAGETYPE_JPC`	`application/octet-stream`
`IMAGETYPE_JP2`	`image/jp2`
`IMAGETYPE_JPX`	`application/octet-stream`
`IMAGETYPE_JB2`	`application/octet-stream`
`IMAGETYPE_SWC`	`application/x-shockwave-flash`
`IMAGETYPE_IFF`	`image/iff`
`IMAGETYPE_WBMP`	`image/vnd.wap.wbmp`
`IMAGETYPE_XBM`	`image/xbm`

Nota: This function does not require the GD image library.

image2wbmp

(PHP 4 >= 4.0.5, PHP 5)

image2wbmp -- Rende disponibile l'immagine per il browser o la salva in un file

Descrizione

int image2wbmp ( resource image [, string filename [, int threshold]] )

image2wbmp() crea un file WBMP dall'immagine specificata nel parametro image. L'argomento image è quello ritornato dalla funzione imagecreate().

L'argomento filename è opzionale, e può essere omesso. Puoi creare uno script PHP che ha direttamente un'immagine WBMP come output inviando image/vnd.wap.wbmp insieme alla funzione header().

Nota: Il supporto per WBMP è disponibile solo se PHP è compilato assieme a GD-1.8 o superiori.

Vedere anche imagewbmp().

imagealphablending

(PHP 4 >= 4.0.6, PHP 5)

imagealphablending -- Set the blending mode for an image

Description

bool imagealphablending ( resource image, bool blendmode )

imagealphablending() allows for two different modes of drawing on truecolor images. In blending mode, the alpha channel component of the color supplied to all drawing function, such as imagesetpixel() determines how much of the underlying color should be allowed to shine through. As a result, gd automatically blends the existing color at that point with the drawing color, and stores the result in the image. The resulting pixel is opaque. In non-blending mode, the drawing color is copied literally with its alpha channel information, replacing the destination pixel. Blending mode is not available when drawing on palette images. If blendmode is TRUE, then blending mode is enabled, otherwise disabled. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Nota: This function requires GD 2.0.1 or later.

imageantialias

(PHP 4 >= 4.3.2, PHP 5)

imageantialias -- Should antialias functions be used or not

Description

bool imageantialias ( resource im, bool on )

Activate the fast drawing antialiased methods for lines and wired polygons. It does not support alpha components. It works using a direct blend operation. It works only with truecolor images.

Thickness and styled are not supported.

Using antialiased primitives with transparent background color can end with some unexpected results. The blend method uses the background color as any other colors. The lack of alpha component support does not allow an alpha based antialiasing method.

Nota: Questa funzione è disponibile soltanto se il PHP ` compilato con la libreria GD allegata.

imagearc

(PHP 3, PHP 4, PHP 5)

imagearc -- Draw a partial ellipse

Description

bool imagearc ( resource image, int cx, int cy, int w, int h, int s, int e, int color )

imagearc() draws a partial ellipse centered at cx, cy (top left is 0, 0) in the image represented by image. W and h specifies the ellipse's width and height respectively while the start and end points are specified in degrees indicated by the s and e arguments. 0° is located at the three-o'clock position, and the arc is drawn clockwise.

Esempio 1. Drawing a circle with imagearc()

<?php

// create a 200*200 image
$img = imagecreatetruecolor(200, 200);

// allocate some colors
$white = imagecolorallocate($img, 255, 255, 255);
$black = imagecolorallocate($img, 0, 0, 0);
   
// draw a black circle 
imagearc($img, 100, 100, 150, 150, 0, 360, $black);

// output image in the browser
header("Content-type: image/png");
imagepng($img);
   
// free memory
imagedestroy($img);

?>

imagechar

(PHP 3, PHP 4, PHP 5)

imagechar -- Draw a character horizontally

Description

bool imagechar ( resource image, int font, int x, int y, string c, int color )

imagechar() draws the first character of c in the image identified by image with its upper-left at x,y (top left is 0, 0) with the color color. If font is 1, 2, 3, 4 or 5, a built-in font is used (with higher numbers corresponding to larger fonts).

Esempio 1. imagechar() example
<?php $im = imagecreatetruecolor(100, 100); $string = 'PHP'; $bg = imagecolorallocate($im, 255, 255, 255); $black = imagecolorallocate($im, 0, 0, 0); // prints a black "P" in the top left corner imagechar($im, 1, 0, 0, $string, $black); header('Content-type: image/png'); imagepng($im); ?>

imagecharup

(PHP 3, PHP 4, PHP 5)

imagecharup -- Draw a character vertically

Description

bool imagecharup ( resource image, int font, int x, int y, string c, int color )

imagecharup() draws the character c vertically in the image identified by image at coordinates x, y (top left is 0, 0) with the color color. If font is 1, 2, 3, 4 or 5, a built-in font is used.

Esempio 1. imagecharup() example
<?php $im = imagecreatetruecolor(100, 100); $string = 'Note that the first letter is a N'; $bg = imagecolorallocate($im, 255, 255, 255); $black = imagecolorallocate($im, 0, 0, 0); // prints a black "Z" on a white background imagecharup($im, 3, 10, 10, $string, $black); header('Content-type: image/png'); imagepng($im); ?>

See also imagechar() and imageloadfont().

imagecolorallocate

(PHP 3, PHP 4, PHP 5)

imagecolorallocate -- Allocate a color for an image

Description

int imagecolorallocate ( resource image, int red, int green, int blue )

imagecolorallocate() returns a color identifier representing the color composed of the given RGB components. The image argument is the return from the imagecreatetruecolor() function. red, green and blue are the values of the red, green and blue component of the requested color respectively. These parameters are integers between 0 and 255 or hexadecimals between 0x00 and 0xFF. imagecolorallocate() must be called to create each color that is to be used in the image represented by image.

Nota: The first call to imagecolorallocate() fills the background color.

<?php

$im = imagecreatetruecolor('example.jpg');
// sets background to red
$background = imagecolorallocate($im, 255, 0, 0);

// sets some colors
$white = imagecolorallocate($im, 255, 255, 255);
$black = imagecolorallocate($im, 0, 0, 0);

// hexadecimal way
$white = imagecolorallocate($im, 0xFF, 0xFF, 0xFF);
$black = imagecolorallocate($im, 0x00, 0x00, 0x00);

?>

Returns -1 if the allocation failed.

imagecolorallocatealpha

(PHP 4 >= 4.3.2, PHP 5)

imagecolorallocatealpha -- Allocate a color for an image

Description

int imagecolorallocatealpha ( resource image, int red, int green, int blue, int alpha )

imagecolorallocatealpha() behaves identically to imagecolorallocate() with the addition of the transparency parameter alpha which may have a value between 0 and 127. 0 indicates completely opaque while 127 indicates completely transparent.

Returns FALSE if the allocation failed.

Esempio 1. Example of using imagecolorallocatealpha()
<?php $size = 300; $image=imagecreatetruecolor($size, $size); // something to get a white background with black border $back = imagecolorallocate($image, 255, 255, 255); $border = imagecolorallocate($image, 0, 0, 0); imagefilledrectangle($image, 0, 0, $size - 1, $size - 1, $back); imagerectangle($image, 0, 0, $size - 1, $size - 1, $border); $yellow_x = 100; $yellow_y = 75; $red_x = 120; $red_y = 165; $blue_x = 187; $blue_y = 125; $radius = 150; // allocate colors with alpha values $yellow = imagecolorallocatealpha($image, 255, 255, 0, 75); $red = imagecolorallocatealpha($image, 255, 0, 0, 75); $blue = imagecolorallocatealpha($image, 0, 0, 255, 75); // drawing 3 overlapped circle imagefilledellipse($image, $yellow_x, $yellow_y, $radius, $radius, $yellow); imagefilledellipse($image, $red_x, $red_y, $radius, $radius, $red); imagefilledellipse($image, $blue_x, $blue_y, $radius, $radius, $blue); // don't forget to output a correct header! header('Content-type: image/png'); // and finally, output the result imagepng($image); imagedestroy($image); ?>

Nota: This function requires GD 2.0.1 or later.

imagecolorat

(PHP 3, PHP 4, PHP 5)

imagecolorat -- Get the index of the color of a pixel

Description

int imagecolorat ( resource image, int x, int y )

Returns the index of the color of the pixel at the specified location in the image specified by image.

If PHP is compiled against GD library 2.0 or higher and the image is a truecolor image, this function returns the RGB value of that pixel as integer. Use bitshifting and masking to access the distinct red, green and blue component values:
Esempio 1. Access distinct RGB values
<?php $im = ImageCreateFromPng("rockym.png"); $rgb = ImageColorAt($im, 100, 100); $r = ($rgb >> 16) & 0xFF; $g = ($rgb >> 8) & 0xFF; $b = $rgb & 0xFF; ?>

imagecolorclosest

(PHP 3, PHP 4, PHP 5)

imagecolorclosest -- Get the index of the closest color to the specified color

Description

int imagecolorclosest ( resource image, int red, int green, int blue )

int imagecolorexact ( resource image, int red, int green, int blue )

Returns the index of the specified color in the palette of the image.

If the color does not exist in the image's palette, -1 is returned.

If you created the image from a file, only colors used in the image are resolved. Colors present only in the pallete are not resolved.

imagecolorexactalpha

(PHP 4 >= 4.0.6, PHP 5)

imagecolorexactalpha -- Get the index of the specified color + alpha

Description

int imagecolorexactalpha ( resource image, int red, int green, int blue, int alpha )

Returns the index of the specified color+alpha in the palette of the image.

If the color does not exist in the image's palette, -1 is returned.

Nota: This function requires GD 2.0.1 or later.

imagecolormatch

(PHP 4 >= 4.3.0, PHP 5)

imagecolormatch -- Makes the colors of the palette version of an image more closely match the true color version

Description

bool imagecolormatch ( resource image1, resource image2 )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

image1 must be Truecolor, image2 must be Palette, and both image1 and image2 must be the same size.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Nota: Questa funzione è disponibile soltanto se il PHP ` compilato con la libreria GD allegata.

Nota: This function requires GD 2.0.1 or later.

(PHP 3, PHP 4, PHP 5)

imagecolorsforindex -- Get the colors for an index

Description

array imagecolorsforindex ( resource image, int index )

This returns an associative array with red, green, blue and alpha keys that contain the appropriate values for the specified color index.

Esempio 1. imagecolorsforindex() example
<?php // open an image $im = imagecreatefrompng('nexen.png'); // get a color $start_x = 40; $start_y = 50; $color_index = imagecolorat($im, $start_x, $start_y); // make it human readable $color_tran = imagecolorsforindex($im, $color_index); // what is it ? echo '<pre>'; print_r($color_tran); echo '</pre>'; ?>
This example will output :
Array ( [red] => 226 [green] => 222 [blue] => 252 [alpha] => 0 )

imagecolorstotal

bool imageconvolution ( resource image, array matrix3x3, float div, float offset )

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Nota: Questa funzione è disponibile soltanto se il PHP ` compilato con la libreria GD allegata.

imagecopy

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

imagecopy -- Copy part of an image

Description

bool imagecopy ( resource dst_im, resource src_im, int dst_x, int dst_y, int src_x, int src_y, int src_w, int src_h )

imagecopymerge

(PHP 4 >= 4.0.1, PHP 5)

imagecopymerge -- Copy and merge part of an image

Description

bool imagecopymerge ( resource dst_im, resource src_im, int dst_x, int dst_y, int src_x, int src_y, int src_w, int src_h, int pct )

Copy a part of src_im onto dst_im starting at the x,y coordinates src_x, src_y with a width of src_w and a height of src_h. The portion defined will be copied onto the x,y coordinates, dst_x and dst_y. The two images will be merged according to pct which can range from 0 to 100. When pct = 0, no action is taken, when 100 this function behaves identically to imagecopy() for pallete images, while it implements alpha transparency for true colour images.

Nota: This function was added in PHP 4.0.6

imagecopymergegray

(PHP 4 >= 4.0.6, PHP 5)

imagecopymergegray -- Copy and merge part of an image with gray scale

Description

bool imagecopymergegray ( resource dst_im, resource src_im, int dst_x, int dst_y, int src_x, int src_y, int src_w, int src_h, int pct )

imagecopymergegray() copy a part of src_im onto dst_im starting at the x,y coordinates src_x, src_y with a width of src_w and a height of src_h. The portion defined will be copied onto the x,y coordinates, dst_x and dst_y. The two images will be merged according to pct which can range from 0 to 100. When pct = 0, no action is taken, when 100 this function behaves identically to imagecopy().

This function is identical to imagecopymerge() except that when merging it preserves the hue of the source by converting the destination pixels to gray scale before the copy operation.

Nota: This function was added in PHP 4.0.6

imagecopyresampled

(PHP 4 >= 4.0.6, PHP 5)

imagecopyresampled -- Copy and resize part of an image with resampling

Description

bool imagecopyresampled ( resource dst_image, resource src_image, int dst_x, int dst_y, int src_x, int src_y, int dst_w, int dst_h, int src_w, int src_h )

imagecopyresampled() copies a rectangular portion of one image to another image, smoothly interpolating pixel values so that, in particular, reducing the size of an image still retains a great deal of clarity. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

dst_image is the destination image, src_image is the source image identifier. If the source and destination coordinates and width and heights differ, appropriate stretching or shrinking of the image fragment will be performed. The coordinates refer to the upper left corner. This function can be used to copy regions within the same image (if dst_image is the same as src_image) but if the regions overlap the results will be unpredictable.

Nota: There is a problem due to palette image limitations (255+1 colors). Resampling or filtering an image commonly needs more colors than 255, a kind of approximation is used to calculate the new resampled pixel and its color. With a palette image we try to allocate a new color, if that failed, we choose the closest (in theory) computed color. This is not always the closest visual color. That may produce a weird result, like blank (or visually blank) images. To skip this problem, please use a truecolor image as a destination image, such as one created by imagecreatetruecolor().

Nota: This function requires GD 2.0.1 or later.

Esempi

Esempio 1. Simple example
This example will resample an image to half its original size.
<?php // The file $filename = 'test.jpg'; $percent = 0.5; // Content type header('Content-type: image/jpeg'); // Get new dimensions list($width, $height) = getimagesize($filename); $new_width = $width * $percent; $new_height = $height * $percent; // Resample $image_p = imagecreatetruecolor($new_width, $new_height); $image = imagecreatefromjpeg($filename); imagecopyresampled($image_p, $image, 0, 0, 0, 0, $new_width, $new_height, $width, $height); // Output imagejpeg($image_p, null, 100); ?>

Esempio 2. Resampling an image proportionally
This example will display an image with the maximum width, or height, of 200 pixels.
<?php // The file $filename = 'test.jpg'; // Set a maximum height and width $width = 200; $height = 200; // Content type header('Content-type: image/jpeg'); // Get new dimensions list($width_orig, $height_orig) = getimagesize($filename); if ($width && ($width_orig < $height_orig)) { $width = ($height / $height_orig) * $width_orig; } else { $height = ($width / $width_orig) * $height_orig; } // Resample $image_p = imagecreatetruecolor($width, $height); $image = imagecreatefromjpeg($filename); imagecopyresampled($image_p, $image, 0, 0, 0, 0, $width, $height, $width_orig, $height_orig); // Output imagejpeg($image_p, null, 100); ?>

Vedere anche:

imagecopyresized()

imagecopyresized

(PHP 3, PHP 4, PHP 5)

imagecopyresized -- Copy and resize part of an image

Description

bool imagecopyresized ( resource dst_image, resource src_image, int dst_x, int dst_y, int src_x, int src_y, int dst_w, int dst_h, int src_w, int src_h )

imagecopyresized() copies a rectangular portion of one image to another image. dst_image is the destination image, src_image is the source image identifier. If the source and destination coordinates and width and heights differ, appropriate stretching or shrinking of the image fragment will be performed. The coordinates refer to the upper left corner. This function can be used to copy regions within the same image (if dst_image is the same as src_image) but if the regions overlap the results will be unpredictable.

Nota: There is a problem due to palette image limitations (255+1 colors). Resampling or filtering an image commonly needs more colors than 255, a kind of approximation is used to calculate the new resampled pixel and its color. With a palette image we try to allocate a new color, if that failed, we choose the closest (in theory) computed color. This is not always the closest visual color. That may produce a weird result, like blank (or visually blank) images. To skip this problem, please use a truecolor image as a destination image, such as one created by imagecreatetruecolor().

Esempi

Esempio 1. Resizing an image
This example will display the image at half size.
<?php // File and new size $filename = 'test.jpg'; $percent = 0.5; // Content type header('Content-type: image/jpeg'); // Get new sizes list($width, $height) = getimagesize($filename); $newwidth = $width * $percent; $newheight = $height * $percent; // Load $thumb = imagecreatetruecolor($newwidth, $newheight); $source = imagecreatefromjpeg($filename); // Resize imagecopyresized($thumb, $source, 0, 0, 0, 0, $newwidth, $newheight, $width, $height); // Output imagejpeg($thumb); ?>
The image will be output at half size, though better quality could be obtained using imagecopyresampled().

Vedere anche:

imagecopyresampled()

imagecreate

(PHP 3, PHP 4, PHP 5)

imagecreate -- Create a new palette based image

Description

resource imagecreate ( int x_size, int y_size )

imagecreate() returns an image identifier representing a blank image of size x_size by y_size.

We recommend the use of imagecreatetruecolor().

Esempio 1. Creating a new GD image stream and outputting an image.
<?php header("Content-type: image/png"); $im = @imagecreate(100, 50) or die("Cannot Initialize new GD image stream"); $background_color = imagecolorallocate($im, 255, 255, 255); $text_color = imagecolorallocate($im, 233, 14, 91); imagestring($im, 1, 5, 5, "A Simple Text String", $text_color); imagepng($im); imagedestroy($im); ?>

imagecreatefromgd2

(PHP 4 >= 4.1.0, PHP 5)

imagecreatefromgd2 -- Create a new image from GD2 file or URL

Description

resource imagecreatefromgd2 ( string filename )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Nota: This function requires GD 2.0.1 or later.

Suggerimento: È possibile utilizzare una URL come un nome di file con questa funzione se fopen wrappers è stata abilitata. Per maggiori informazioni su come specificare i nomi di file vedere fopen() e Appendice M per avere la lista dei protocolli URL supportati.

Avvertimento

la versione per Windows di PHP antecedente la 4.3.0 non supporta l'accesso remoto ai file da parte di questa funzione, anche se allow_url_fopen è abilitato.

imagecreatefromgd2part

(PHP 4 >= 4.1.0, PHP 5)

imagecreatefromgd2part -- Create a new image from a given part of GD2 file or URL

Description

resource imagecreatefromgd2part ( string filename, int srcX, int srcY, int width, int height )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Nota: This function requires GD 2.0.1 or later.

Suggerimento: È possibile utilizzare una URL come un nome di file con questa funzione se fopen wrappers è stata abilitata. Per maggiori informazioni su come specificare i nomi di file vedere fopen() e Appendice M per avere la lista dei protocolli URL supportati.

Avvertimento

la versione per Windows di PHP antecedente la 4.3.0 non supporta l'accesso remoto ai file da parte di questa funzione, anche se allow_url_fopen è abilitato.

imagecreatefromgd

(PHP 4 >= 4.1.0, PHP 5)

imagecreatefromgd -- Create a new image from GD file or URL

Description

resource imagecreatefromgd ( string filename )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Suggerimento: È possibile utilizzare una URL come un nome di file con questa funzione se fopen wrappers è stata abilitata. Per maggiori informazioni su come specificare i nomi di file vedere fopen() e Appendice M per avere la lista dei protocolli URL supportati.

Avvertimento

la versione per Windows di PHP antecedente la 4.3.0 non supporta l'accesso remoto ai file da parte di questa funzione, anche se allow_url_fopen è abilitato.

imagecreatefromgif

(PHP 3, PHP 4, PHP 5)

imagecreatefromgif -- Create a new image from file or URL

Description

resource imagecreatefromgif ( string filename )

imagecreatefromgif() returns an image identifier representing the image obtained from the given filename.

imagecreatefromgif() returns an empty string on failure. It also outputs an error message, which unfortunately displays as a broken link in a browser. To ease debugging the following example will produce an error GIF:
Esempio 1. Example to handle an error during creation
<?php function LoadGif ($imgname) { $im = @imagecreatefromgif ($imgname); /* Attempt to open */ if (!$im) { /* See if it failed */ $im = imagecreatetruecolor (150, 30); /* Create a blank image */ $bgc = imagecolorallocate ($im, 255, 255, 255); $tc = imagecolorallocate ($im, 0, 0, 0); imagefilledrectangle ($im, 0, 0, 150, 30, $bgc); /* Output an errmsg */ imagestring ($im, 1, 5, 5, "Error loading $imgname", $tc); } return $im; } ?>

Nota: GIF support was removed from the GD library in Version 1.6, and added back in Version 2.0.28. This function is not available between these versions.

Suggerimento: È possibile utilizzare una URL come un nome di file con questa funzione se fopen wrappers è stata abilitata. Per maggiori informazioni su come specificare i nomi di file vedere fopen() e Appendice M per avere la lista dei protocolli URL supportati.

Avvertimento

la versione per Windows di PHP antecedente la 4.3.0 non supporta l'accesso remoto ai file da parte di questa funzione, anche se allow_url_fopen è abilitato.

imagecreatefromjpeg

(PHP 3 >= 3.0.16, PHP 4, PHP 5)

imagecreatefromjpeg -- Create a new image from file or URL

Description

resource imagecreatefromjpeg ( string filename )

imagecreatefromjpeg() returns an image identifier representing the image obtained from the given filename.

imagecreatefromjpeg() returns an empty string on failure. It also outputs an error message, which unfortunately displays as a broken link in a browser. To ease debugging the following example will produce an error JPEG:
Esempio 1. Example to handle an error during creation
<?php function LoadJpeg($imgname) { $im = @imagecreatefromjpeg($imgname); /* Attempt to open */ if (!$im) { /* See if it failed */ $im = imagecreatetruecolor(150, 30); /* Create a black image */ $bgc = imagecolorallocate($im, 255, 255, 255); $tc = imagecolorallocate($im, 0, 0, 0); imagefilledrectangle($im, 0, 0, 150, 30, $bgc); /* Output an errmsg */ imagestring($im, 1, 5, 5, "Error loading $imgname", $tc); } return $im; } ?>

Nota: JPEG support is only available if PHP was compiled against GD-1.8 or later.

Suggerimento: È possibile utilizzare una URL come un nome di file con questa funzione se fopen wrappers è stata abilitata. Per maggiori informazioni su come specificare i nomi di file vedere fopen() e Appendice M per avere la lista dei protocolli URL supportati.

Avvertimento

la versione per Windows di PHP antecedente la 4.3.0 non supporta l'accesso remoto ai file da parte di questa funzione, anche se allow_url_fopen è abilitato.

imagecreatefrompng

(PHP 3 >= 3.0.13, PHP 4, PHP 5)

imagecreatefrompng -- Create a new image from file or URL

Description

resource imagecreatefrompng ( string filename )

imagecreatefrompng() returns an image identifier representing the image obtained from the given filename.

imagecreatefrompng() returns an empty string on failure. It also outputs an error message, which unfortunately displays as a broken link in a browser. To ease debugging the following example will produce an error PNG:
Esempio 1. Example to handle an error during creation
<?php function LoadPNG($imgname) { $im = @imagecreatefrompng($imgname); /* Attempt to open */ if (!$im) { /* See if it failed */ $im = imagecreatetruecolor(150, 30); /* Create a blank image */ $bgc = imagecolorallocate($im, 255, 255, 255); $tc = imagecolorallocate($im, 0, 0, 0); imagefilledrectangle($im, 0, 0, 150, 30, $bgc); /* Output an errmsg */ imagestring($im, 1, 5, 5, "Error loading $imgname", $tc); } return $im; } ?>

Suggerimento: È possibile utilizzare una URL come un nome di file con questa funzione se fopen wrappers è stata abilitata. Per maggiori informazioni su come specificare i nomi di file vedere fopen() e Appendice M per avere la lista dei protocolli URL supportati.

Avvertimento

la versione per Windows di PHP antecedente la 4.3.0 non supporta l'accesso remoto ai file da parte di questa funzione, anche se allow_url_fopen è abilitato.

imagecreatefromstring

(PHP 4 >= 4.0.4, PHP 5)

imagecreatefromstring -- Create a new image from the image stream in the string

Descrizione

resource imagecreatefromstring ( string image )

imagecreatefromstring() returns an image identifier representing the image obtained from the given string. These types will be automatically detected if your build of PHP supports them: JPEG, PNG, GIF, WBMP, and GD2.

Valori restituiti

An image resource will be returned on success. FALSE is returned if the image type is unsupported, the data is not in a recognised format, or the image is corrupt and cannot be loaded.

Esempi

Esempio 1. imagecreatefromstring() example
<?php $data = 'iVBORw0KGgoAAAANSUhEUgAAABwAAAASCAMAAAB/2U7WAAAABl' . 'BMVEUAAAD///+l2Z/dAAAASUlEQVR4XqWQUQoAIAxC2/0vXZDr' . 'EX4IJTRkb7lobNUStXsB0jIXIAMSsQnWlsV+wULF4Avk9fLq2r' . '8a5HSE35Q3eO2XP1A1wQkZSgETvDtKdQAAAABJRU5ErkJggg=='; $data = base64_decode($data); $im = imagecreatefromstring($data); if ($im !== false) { header('Content-Type: image/png'); imagepng($im); } else { echo 'An error occured.'; } ?>

Vedere anche:

imagecreatefromjpeg()

imagecreatefrompng()

imagecreatefromgif()

imagecreatetruecolor()

imagecreatefromwbmp

(PHP 4 >= 4.0.1, PHP 5)

imagecreatefromwbmp -- Create a new image from file or URL

Description

resource imagecreatefromwbmp ( string filename )

imagecreatefromwbmp() returns an image identifier representing the image obtained from the given filename.

imagecreatefromwbmp() returns an empty string on failure. It also outputs an error message, which unfortunately displays as a broken link in a browser. To ease debugging the following example will produce an error WBMP:
Esempio 1. Example to handle an error during creation
<?php function LoadWBMP($imgname) { $im = @imagecreatefromwbmp($imgname); /* Attempt to open */ if (!$im) { /* See if it failed */ $im = imagecreatetruecolor (20, 20); /* Create a blank image */ $bgc = imagecolorallocate($im, 255, 255, 255); $tc = imagecolorallocate($im, 0, 0, 0); imagefilledrectangle($im, 0, 0, 10, 10, $bgc); /* Output an errmsg */ imagestring($im, 1, 5, 5, "Error loading $imgname", $tc); } return $im; } ?>

Nota: WBMP support is only available if PHP was compiled against GD-1.8 or later.

Suggerimento: È possibile utilizzare una URL come un nome di file con questa funzione se fopen wrappers è stata abilitata. Per maggiori informazioni su come specificare i nomi di file vedere fopen() e Appendice M per avere la lista dei protocolli URL supportati.

Avvertimento

la versione per Windows di PHP antecedente la 4.3.0 non supporta l'accesso remoto ai file da parte di questa funzione, anche se allow_url_fopen è abilitato.

imagecreatefromxbm

(PHP 4 >= 4.0.1, PHP 5)

imagecreatefromxbm -- Create a new image from file or URL

Description

resource imagecreatefromxbm ( string filename )

imagecreatefromxbm() returns an image identifier representing the image obtained from the given filename.

Suggerimento: È possibile utilizzare una URL come un nome di file con questa funzione se fopen wrappers è stata abilitata. Per maggiori informazioni su come specificare i nomi di file vedere fopen() e Appendice M per avere la lista dei protocolli URL supportati.

Avvertimento

la versione per Windows di PHP antecedente la 4.3.0 non supporta l'accesso remoto ai file da parte di questa funzione, anche se allow_url_fopen è abilitato.

imagecreatefromxpm

(PHP 4 >= 4.0.1, PHP 5)

imagecreatefromxpm -- Create a new image from file or URL

Description

resource imagecreatefromxpm ( string filename )

imagecreatefromxpm() returns an image identifier representing the image obtained from the given filename.

Nota: Questa funzione è disponibile soltanto se il PHP ` compilato con la libreria GD allegata.

Suggerimento: È possibile utilizzare una URL come un nome di file con questa funzione se fopen wrappers è stata abilitata. Per maggiori informazioni su come specificare i nomi di file vedere fopen() e Appendice M per avere la lista dei protocolli URL supportati.

Avvertimento

la versione per Windows di PHP antecedente la 4.3.0 non supporta l'accesso remoto ai file da parte di questa funzione, anche se allow_url_fopen è abilitato.

imagecreatetruecolor

(PHP 4 >= 4.0.6, PHP 5)

imagecreatetruecolor -- Create a new true color image

Description

resource imagecreatetruecolor ( int x_size, int y_size )

imagecreatetruecolor() returns an image identifier representing a black image of size x_size by y_size.

Depending on your PHP and GD versions this function is defined or not. With PHP 4.0.6 through 4.1.x this function always exists if the GD module is loaded, but calling it without GD2 being installed PHP will issue a fatal error and exit. With PHP 4.2.x this behaviour is differnet in issueing a warning instead of an error. Other versions only define this function, if the correct GD version is installed.

Esempio 1. Creating a new GD image stream and outputting an image.
<?php header ("Content-type: image/png"); $im = @imagecreatetruecolor(50, 100) or die("Cannot Initialize new GD image stream"); $text_color = imagecolorallocate($im, 233, 14, 91); imagestring($im, 1, 5, 5, "A Simple Text String", $text_color); imagepng($im); imagedestroy($im); ?>

Nota: This function requires GD 2.0.1 or later.

Nota: This function will not work with GIF file formats.

Nota: This function was added in PHP 4.0.6 and requires GD 2.0.2 or later which can be obtained at http://www.boutell.com/gd/

Esempio 1. imageellipse() example
<?php // create a blank image $image = imagecreatetruecolor(400, 300); // fill the background color $bg = imagecolorallocate($image, 0, 0, 0); // choose a color for the ellipse $col_ellipse = imagecolorallocate($image, 255, 255, 255); // draw the ellipse imageellipse($image, 200, 150, 300, 200, $col_ellipse); // output the picture header("Content-type: image/png"); imagepng($image); ?>

imagefill

(PHP 3, PHP 4, PHP 5)

imagefill -- Flood fill

Description

bool imagefill ( resource image, int x, int y, int color )

imagefill() performs a flood fill starting at coordinate x, y (top left is 0, 0) with color color in the image image.

imagefilledarc

(PHP 4 >= 4.0.6, PHP 5)

imagefilledarc -- Draw a partial ellipse and fill it

Description

bool imagefilledarc ( resource image, int cx, int cy, int w, int h, int s, int e, int color, int style )

imagefilledarc() draws a partial ellipse centered at cx, cy (top left is 0, 0) in the image represented by image. Restituisce TRUE in caso di successo, FALSE in caso di fallimento. W and h specifies the ellipse's width and height respectively while the start and end points are specified in degrees indicated by the s and e arguments. style is a bitwise OR of the following possibilities:

IMG_ARC_PIE
IMG_ARC_CHORD
IMG_ARC_NOFILL
IMG_ARC_EDGED

IMG_ARC_PIE and IMG_ARC_CHORD are mutually exclusive; IMG_ARC_CHORD just connects the starting and ending angles with a straight line, while IMG_ARC_PIE produces a rounded edge. IMG_ARC_NOFILL indicates that the arc or chord should be outlined, not filled. IMG_ARC_EDGED, used together with IMG_ARC_NOFILL, indicates that the beginning and ending angles should be connected to the center - this is a good way to outline (rather than fill) a 'pie slice'.

Esempio 1. Creating a 3D looking pie
<?php // create image $image = imagecreatetruecolor(100, 100); // allocate some solors $white = imagecolorallocate($image, 0xFF, 0xFF, 0xFF); $gray = imagecolorallocate($image, 0xC0, 0xC0, 0xC0); $darkgray = imagecolorallocate($image, 0x90, 0x90, 0x90); $navy = imagecolorallocate($image, 0x00, 0x00, 0x80); $darknavy = imagecolorallocate($image, 0x00, 0x00, 0x50); $red = imagecolorallocate($image, 0xFF, 0x00, 0x00); $darkred = imagecolorallocate($image, 0x90, 0x00, 0x00); // make the 3D effect for ($i = 60; $i > 50; $i--) { imagefilledarc($image, 50, $i, 100, 50, 0, 45, $darknavy, IMG_ARC_PIE); imagefilledarc($image, 50, $i, 100, 50, 45, 75 , $darkgray, IMG_ARC_PIE); imagefilledarc($image, 50, $i, 100, 50, 75, 360 , $darkred, IMG_ARC_PIE); } imagefilledarc($image, 50, 50, 100, 50, 0, 45, $navy, IMG_ARC_PIE); imagefilledarc($image, 50, 50, 100, 50, 45, 75 , $gray, IMG_ARC_PIE); imagefilledarc($image, 50, 50, 100, 50, 75, 360 , $red, IMG_ARC_PIE); // flush image header('Content-type: image/png'); imagepng($image); imagedestroy($image); ?>

Nota: This function requires GD 2.0.1 or later.

imagefilledellipse

(PHP 4 >= 4.0.6, PHP 5)

imagefilledellipse -- Draw a filled ellipse

Description

bool imagefilledellipse ( resource image, int cx, int cy, int w, int h, int color )

imagefilledellipse() draws an ellipse centered at cx, cy (top left is 0, 0) in the image represented by image. W and h specifies the ellipse's width and height respectively. The ellipse is filled using color. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempio 1. imagefilledellipse() example
<?php // create a blank image $image = imagecreatetruecolor(400, 300); // fill the background color $bg = imagecolorallocate($image, 0, 0, 0); // choose a color for the ellipse $col_ellipse = imagecolorallocate($image, 255, 255, 255); // draw the white ellipse imagefilledellipse($image, 200, 150, 300, 200, $col_ellipse); // output the picture header("Content-type: image/png"); imagepng($image); ?>

Nota: This function requires GD 2.0.1 or later.

filtertype can be one of the following:

IMG_FILTER_NEGATE: Reverses all colors of the image.
IMG_FILTER_GRAYSCALE: Converts the image into grayscale.
IMG_FILTER_BRIGHTNESS: Changes the brightness of the image. Use arg1 to set the level of brightness.
IMG_FILTER_CONTRAST: Changes the contrast of the image. Use arg1 to set the level of contrast.
IMG_FILTER_COLORIZE: Like IMG_FILTER_GRAYSCALE, except you can specify the color. Use arg1, arg2 and arg3 in the form of red, blue, green. The range for each color is 0 to 255.
IMG_FILTER_EDGEDETECT: Uses edge detection to highlight the edges in the image.
IMG_FILTER_EMBOSS: Embosses the image.
IMG_FILTER_GAUSSIAN_BLUR: Blurs the image using the Gaussian method.
IMG_FILTER_SELECTIVE_BLUR: Blurs the image.
IMG_FILTER_MEAN_REMOVAL: Uses mean removal to achieve a "sketchy" effect.
IMG_FILTER_SMOOTH: Makes the image smoother. Use arg1 to set the level of smoothness.

Nota: Questa funzione è disponibile soltanto se il PHP ` compilato con la libreria GD allegata.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempio 1. imagefilter() grayscale example
<?php $im = imagecreatefrompng('dave.png'); if ($im && imagefilter($im, IMG_FILTER_GRAYSCALE)) { echo 'Image converted to grayscale.'; imagepng($im, 'dave.png'); } else { echo 'Conversion to grayscale failed.'; } imagedestroy($im); ?>

array imageftbbox ( float size, float angle, string font_file, string text [, array extrainfo] )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Nota: This function requires GD 2.0.1 or later.

Nota: Parameter extrainfo is optional since PHP 4.3.5.

imagefttext

(PHP 4 >= 4.1.0, PHP 5)

imagefttext -- Write text to the image using fonts using FreeType 2

Description

array imagefttext ( resource image, float size, float angle, int x, int y, int col, string font_file, string text [, array extrainfo] )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Nota: This function requires GD 2.0.1 or later.

Nota: Parameter extrainfo is optional since PHP 4.3.5.

imagegammacorrect

(PHP 3 >= 3.0.13, PHP 4, PHP 5)

imagegammacorrect -- Apply a gamma correction to a GD image

Description

bool imagegammacorrect ( resource image, float inputgamma, float outputgamma )

The imagegammacorrect() function applies gamma correction to a gd image stream (image) given an input gamma, the parameter inputgamma and an output gamma, the parameter outputgamma.

imagegd2

(PHP 4 >= 4.1.0, PHP 5)

imagegd2 -- Output GD2 image to browser or file

Description

bool imagegd2 ( resource image [, string filename [, int chunk_size [, int type]]] )

imagegd2() outputs a GD2 image to filename. The image parameter is the return from the imagecreatetruecolor() function.

The filename parameter is optional, and if left off, the raw image stream will be output directly.

The optional type parameter is either IMG_GD2_RAW or IMG_GD2_COMPRESSED. Default is IMG_GD2_RAW.

Nota: The optional chunk_size and type parameters became available in PHP 4.3.2.

Nota: The GD2 format is commonly used to allow fast loading of parts of images. Note that the GD2 format is only usable in GD2-compatible applications.

Nota: This function requires GD 2.0.1 or later.

imagegd

(PHP 4 >= 4.1.0, PHP 5)

imagegd -- Output GD image to browser or file

Description

bool imagegd ( resource image [, string filename] )

imagegd() outputs a GD image to filename. The image argument is the return from the imagecreatetruecolor() function.

The filename parameter is optional, and if left off, the raw image stream will be output directly.

Nota: The GD format is commonly used to allow fast loading of parts of images. Note that the GD format is only usable in GD-compatible applications.

imagegif

(PHP 3, PHP 4, PHP 5)

imagegif -- Output image to browser or file

Description

bool imagegif ( resource image [, string filename] )

imagegif() creates the GIF file in filename from the image image. The image argument is the return from the imagecreatetruecolor() function.

The image format will be GIF87a unless the image has been made transparent with imagecolortransparent(), in which case the image format will be GIF89a.

The filename argument is optional, and if left off, the raw image stream will be output directly. By sending an image/gif content-type using header(), you can create a PHP script that outputs GIF images directly.

Nota: Since all GIF support was removed from the GD library in version 1.6, this function is not available if you are using that version of the GD library. Support is expected to return in a version subsequent to the rerelease of GIF support in the GD library in mid 2004. For more information, see the GD Project site.
The following code snippet allows you to write more portable PHP applications by auto-detecting the type of GD support which is available. Replace the sequence header ("Content-type: image/gif"); imagegif ($im); by the more flexible sequence:
<?php
if (function_exists("imagegif")) {
    header("Content-type: image/gif");
    imagegif($im);
} elseif (function_exists("imagejpeg")) {
    header("Content-type: image/jpeg");
    imagejpeg($im, "", 0.5);
} elseif (function_exists("imagepng")) {
    header("Content-type: image/png");
    imagepng($im);
} elseif (function_exists("imagewbmp")) {
    header("Content-type: image/vnd.wap.wbmp");
    imagewbmp($im);
} else {
    die("No image support in this PHP server");
}
?>

Nota: As of version 3.0.18 and 4.0.2 you can use the function imagetypes() in place of function_exists() for checking the presence of the various supported image formats:
<?php
if (imagetypes() & IMG_GIF) {
    header ("Content-type: image/gif");
    imagegif ($im);
} elseif (imagetypes() & IMG_JPG) {
    /* ... etc. */
}
?>

imageinterlace

(PHP 3, PHP 4, PHP 5)

imageinterlace -- Enable or disable interlace

Description

int imageinterlace ( resource image [, int interlace] )

imageinterlace() turns the interlace bit on or off. If interlace is 1 the image will be interlaced, and if interlace is 0 the interlace bit is turned off.

If the interlace bit is set and the image is used as a JPEG image, the image is created as a progressive JPEG.

This function returns whether the interlace bit is set for the image.

imageistruecolor

(PHP 4 >= 4.3.2, PHP 5)

imageistruecolor -- Finds whether an image is a truecolor image

Description

bool imageistruecolor ( resource image )

imageistruecolor() finds whether the image image is a truecolor image.

Nota: This function requires GD 2.0.1 or later.

imagejpeg

(PHP 3 >= 3.0.16, PHP 4, PHP 5)

imagejpeg -- Output image to browser or file

Description

bool imagejpeg ( resource image [, string filename [, int quality]] )

imagejpeg() creates the JPEG file in filename from the image image. The image argument is the return from the imagecreatetruecolor() function.

The filename argument is optional, and if left off, the raw image stream will be output directly. To skip the filename argument in order to provide a quality argument just use an empty string (''). By sending an image/jpeg content-type using header(), you can create a PHP script that outputs JPEG images directly.

Nota: JPEG support is only available if PHP was compiled against GD-1.8 or later.

quality is optional, and ranges from 0 (worst quality, smaller file) to 100 (best quality, biggest file). The default is the default IJG quality value (about 75).

If you want to output Progressive JPEGs, you need to set interlacing on with imageinterlace().

imagelayereffect

(PHP 4 >= 4.3.0, PHP 5)

imagelayereffect -- Set the alpha blending flag to use the bundled libgd layering effects

Description

bool imagelayereffect ( resource image, int effect )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Nota: Questa funzione è disponibile soltanto se il PHP ` compilato con la libreria GD allegata.

Nota: This function requires GD 2.0.1 or later.

imageline

(PHP 3, PHP 4, PHP 5)

imageline -- Draw a line

Description

bool imageline ( resource image, int x1, int y1, int x2, int y2, int color )

imageline() draws a line from x1, y1 to x2, y2 (top left is 0, 0) in image image of color color.

Esempio 1. Drawing a thick line

<?php

function imagelinethick($image, $x1, $y1, $x2, $y2, $color, $thick = 1) 
{
    /* this way it works well only for orthogonal lines
    imagesetthickness($image, $thick);
    return imageline($image, $x1, $y1, $x2, $y2, $color);
    */
    if ($thick == 1) {
        return imageline($image, $x1, $y1, $x2, $y2, $color);
    }
    $t = $thick / 2 - 0.5;
    if ($x1 == $x2 || $y1 == $y2) {
        return imagefilledrectangle($image, round(min($x1, $x2) - $t), round(min($y1, $y2) - $t), round(max($x1, $x2) + $t), round(max($y1, $y2) + $t), $color);
    }
    $k = ($y2 - $y1) / ($x2 - $x1); //y = kx + q
    $a = $t / sqrt(1 + pow($k, 2));
    $points = array(
        round($x1 - (1+$k)*$a), round($y1 + (1-$k)*$a),
        round($x1 - (1-$k)*$a), round($y1 - (1+$k)*$a),
        round($x2 + (1+$k)*$a), round($y2 - (1-$k)*$a),
        round($x2 + (1-$k)*$a), round($y2 + (1+$k)*$a),
    );    
    imagefilledpolygon($image, $points, 4, $color);
    return imagepolygon($image, $points, 4, $color);
}

?>

imageloadfont

(PHP 3, PHP 4, PHP 5)

imageloadfont -- Load a new font

Description

int imageloadfont ( string file )

imageloadfont() loads a user-defined bitmap font and returns an identifier for the font (that is always greater than 5, so it will not conflict with the built-in fonts). It returns FALSE in case of error.

The font file format is currently binary and architecture dependent. This means you should generate the font files on the same type of CPU as the machine you are running PHP on.

Tabella 1. Font file format

byte position	C data type	description
byte 0-3	int	number of characters in the font
byte 4-7	int	value of first character in the font (often 32 for space)
byte 8-11	int	pixel width of each character
byte 12-15	int	pixel height of each character
byte 16-	char	array with character data, one byte per pixel in each character, for a total of (ncharswidthheight) bytes.

Esempio 1. Using imageloadfont
<?php $im = imagecreatetruecolor(50, 20); $black = imagecolorallocate($im, 0, 0, 0); $white = imagecolorallocate($im, 255, 255, 255); imagefilledrectangle($im, 0, 0, 49, 19, $white); $font = imageloadfont("04b.gdf"); imagestring($im, $font, 0, 0, "Hello", $black); imagepng($im); ?>

imagepalettecopy

(PHP 4 >= 4.0.1, PHP 5)

imagepalettecopy -- Copy the palette from one image to another

Description

size is expressed in pixels.

space allows you to change the default value of a space in a font. This amount is added to the normal value and can also be negative.

tightness allows you to control the amount of white space between characters. This amount is added to the normal character width and can also be negative.

angle is in degrees.

Parameters space and tightness are expressed in character space units, where 1 unit is 1/1000th of an em-square.

Parameters space, tightness, and angle are optional.

The bounding box is calculated using information available from character metrics, and unfortunately tends to differ slightly from the results achieved by actually rasterizing the text. If the angle is 0 degrees, you can expect the text to need 1 pixel more to every direction.

Nota: Questa funzione è disponibile soltanto se il PHP ` compilato utilizzando --with-t1lib.

This function returns an array containing the following elements:

0	lower left x-coordinate
1	lower left y-coordinate
2	upper right x-coordinate
3	upper right y-coordinate

imagepscopyfont

(PHP 3 >= 3.0.9, PHP 4, PHP 5)

imagepscopyfont -- Make a copy of an already loaded font for further modification

Description

int imagepscopyfont ( resource fontindex )

Use this function if you need make further modifications to the font, for example extending/condensing, slanting it or changing its character encoding vector, but need to keep the original along as well. Note that the font you want to copy must be one obtained using imagepsloadfont(), not a font that is itself a copied one. You can although make modifications to it before copying.

If you use this function, you must free the fonts obtained this way yourself and in reverse order. Otherwise your script will hang.

In the case everything went right, a valid font index will be returned and can be used for further purposes. Otherwise the function returns FALSE and prints a message describing what went wrong.

Nota: Questa funzione è disponibile soltanto se il PHP ` compilato utilizzando --with-t1lib.

imagepsencodefont

(PHP 3 >= 3.0.9, PHP 4, PHP 5)

imagepsencodefont -- Change the character encoding vector of a font

Description

bool imagepsencodefont ( resource font_index, string encodingfile )

Loads a character encoding vector from a file and changes the fonts encoding vector to it. As a PostScript fonts default vector lacks most of the character positions above 127, you'll definitely want to change this if you use an other language than English. The exact format of this file is described in T1libs documentation. T1lib comes with two ready-to-use files, IsoLatin1.enc and IsoLatin2.enc.

If you find yourself using this function all the time, a much better way to define the encoding is to set ps.default_encoding in the configuration file to point to the right encoding file and all fonts you load will automatically have the right encoding.

Nota: Questa funzione è disponibile soltanto se il PHP ` compilato utilizzando --with-t1lib.

imagepsextendfont

(PHP 3 >= 3.0.9, PHP 4, PHP 5)

imagepsextendfont -- Extend or condense a font

Description

bool imagepsextendfont ( int font_index, float extend )

Extend or condense a font (font_index), if the value of the extend parameter is less than one you will be condensing the font.

Nota: Questa funzione è disponibile soltanto se il PHP ` compilato utilizzando --with-t1lib.

imagepsfreefont

(PHP 3 >= 3.0.9, PHP 4, PHP 5)

imagepsfreefont -- Free memory used by a PostScript Type 1 font

Description

bool imagepsfreefont ( resource fontindex )

imagepsfreefont() frees memory used by a PostScript Type 1 font.

Nota: Questa funzione è disponibile soltanto se il PHP ` compilato utilizzando --with-t1lib.

imagepsloadfont

(PHP 3 >= 3.0.9, PHP 4, PHP 5)

imagepsloadfont -- Load a PostScript Type 1 font from file

Description

resource imagepsloadfont ( string filename )

In the case everything went right, a valid font index will be returned and can be used for further purposes. Otherwise the function returns FALSE and prints a message describing what went wrong, which you cannot read directly, while the output type is image.

Esempio 1. imagepsloadfont() example
<?php header("Content-type: image/jpeg"); $im = imagecreatetruecolor(350, 45); $black = imagecolorallocate($im, 0, 0, 0); $white = imagecolorallocate($im, 255, 255, 255); $font = imagepsloadfont("bchbi.pfb"); // or locate your .pfb files on your machine imagepstext($im, "Testing... It worked!", $font, 32, $white, $black, 32, 32); imagepsfreefont($font); imagejpeg($im, "", 100); //for best quality...your mileage may vary imagedestroy($im); ?>

Nota: Questa funzione è disponibile soltanto se il PHP ` compilato utilizzando --with-t1lib.

imagepsslantfont

(PHP 3 >= 3.0.9, PHP 4, PHP 5)

imagepsslantfont -- Slant a font

Description

bool imagepsslantfont ( resource font_index, float slant )

Slant a font given by the font_index parameter with a slant of the value of the slant parameter.

Nota: Questa funzione è disponibile soltanto se il PHP ` compilato utilizzando --with-t1lib.

imagepstext

(PHP 3 >= 3.0.9, PHP 4, PHP 5)

imagepstext -- To draw a text string over an image using PostScript Type1 fonts

Description

array imagepstext ( resource image, string text, resource font, int size, int foreground, int background, int x, int y [, int space, int tightness, float angle, int antialias_steps] )

foreground is the color in which the text will be painted. Background is the color to which the text will try to fade in with antialiasing. No pixels with the color background are actually painted, so the background image does not need to be of solid color.

The coordinates given by x, y will define the origin (or reference point) of the first character (roughly the lower-left corner of the character). This is different from the imagestring(), where x, y define the upper-right corner of the first character. Refer to PostScript documentation about fonts and their measuring system if you have trouble understanding how this works.

space allows you to change the default value of a space in a font. This amount is added to the normal value and can also be negative.

tightness allows you to control the amount of white space between characters. This amount is added to the normal character width and can also be negative.

angle is in degrees.

size is expressed in pixels.

antialias_steps allows you to control the number of colours used for antialiasing text. Allowed values are 4 and 16. The higher value is recommended for text sizes lower than 20, where the effect in text quality is quite visible. With bigger sizes, use 4. It's less computationally intensive.

Parameters space and tightness are expressed in character space units, where 1 unit is 1/1000th of an em-square.

Parameters space, tightness, angle and antialias_steps are optional.

Nota: Questa funzione è disponibile soltanto se il PHP ` compilato utilizzando --with-t1lib.

This function returns an array containing the following elements:

0	lower left x-coordinate
1	lower left y-coordinate
2	upper right x-coordinate
3	upper right y-coordinate

imagerectangle

(PHP 3, PHP 4, PHP 5)

imagerectangle -- Draw a rectangle

Description

bool imagerectangle ( resource image, int x1, int y1, int x2, int y2, int col )

imagerectangle() creates a rectangle of color col in image image starting at upper left coordinate x1, y1 and ending at bottom right coordinate x2, y2. 0, 0 is the top left corner of the image.

imagerotate

(PHP 4 >= 4.3.0, PHP 5)

imagerotate -- Rotate an image with a given angle

Description

resource imagerotate ( resource src_im, float angle, int bgd_color [, int ignore_transparent] )

Rotates the src_im image using a given angle in degrees. bgd_color specifies the color of the uncovered zone after the rotation.

The center of rotation is the center of the image, and the rotated image is scaled down so that the whole rotated image fits in the destination image - the edges are not clipped.

If ignore_transparent is set and non-zero, transparent colors are ignored (otherwise kept). This parameter was added in PHP 5.1.

Esempio 1. Rotate an image 180 degrees
This example rotates an image 180 degrees - upside down.
// File and rotation $filename = 'test.jpg'; $degrees = 180; // Content type header('Content-type: image/jpeg'); // Load $source = imagecreatefromjpeg($filename); // Rotate $rotate = imagerotate($source, $degrees, 0); // Output imagejpeg($rotate);

Nota: Questa funzione è disponibile soltanto se il PHP ` compilato con la libreria GD allegata.

imagesavealpha

(PHP 4 >= 4.3.2, PHP 5)

imagesavealpha -- Set the flag to save full alpha channel information (as opposed to single-color transparency) when saving PNG images

Description

bool imagesavealpha ( resource image, bool saveflag )

imagesavealpha() sets the flag to attempt to save full alpha channel information (as opposed to single-color transparency) when saving PNG images.

You have to unset alphablending (imagealphablending($im, FALSE)), to use it.

Alpha channel is not supported by all browsers, if you have problem with your browser, try to load your script with an alpha channel compliant browser, e.g. latest Mozilla.

Nota: This function requires GD 2.0.1 or later.

imagesetbrush

(PHP 4 >= 4.0.6, PHP 5)

imagesetbrush -- Set the brush image for line drawing

Description

bool imagesetbrush ( resource image, resource brush )

imagesetbrush() sets the brush image to be used by all line drawing functions (such as imageline() and imagepolygon()) when drawing with the special colors IMG_COLOR_BRUSHED or IMG_COLOR_STYLEDBRUSHED.

Nota: You need not take special action when you are finished with a brush, but if you destroy the brush image, you must not use the IMG_COLOR_BRUSHED or IMG_COLOR_STYLEDBRUSHED colors until you have set a new brush image!

Nota: This function was added in PHP 4.0.6

imagesetpixel

(PHP 3, PHP 4, PHP 5)

imagesetpixel -- Set a single pixel

Description

bool imagesetpixel ( resource image, int x, int y, int color )

imagesetpixel() draws a pixel at x, y (top left is 0, 0) in image image of color color.

imagesetstyle

(PHP 4 >= 4.0.6, PHP 5)

imagesetstyle -- Set the style for line drawing

Description

bool imagesetstyle ( resource image, array style )

imagesetstyle() sets the style to be used by all line drawing functions (such as imageline() and imagepolygon()) when drawing with the special color IMG_COLOR_STYLED or lines of images with color IMG_COLOR_STYLEDBRUSHED. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

The style parameter is an array of pixels. Following example script draws a dashed line from upper left to lower right corner of the canvas:
Esempio 1. imagesetstyle() example
<?php header("Content-type: image/jpeg"); $im = imagecreatetruecolor(100, 100); $w = imagecolorallocate($im, 255, 255, 255); $red = imagecolorallocate($im, 255, 0, 0); /* Draw a dashed line, 5 red pixels, 5 white pixels */ $style = array($red, $red, $red, $red, $red, $w, $w, $w, $w, $w); imagesetstyle($im, $style); imageline($im, 0, 0, 100, 100, IMG_COLOR_STYLED); /* Draw a line of happy faces using imagesetbrush() with imagesetstyle */ $style = array($w, $w, $w, $w, $w, $w, $w, $w, $w, $w, $w, $w, $red); imagesetstyle($im, $style); $brush = imagecreatefrompng("http://www.libpng.org/pub/png/images/smile.happy.png"); $w2 = imagecolorallocate($brush, 255, 255, 255); imagecolortransparent($brush, $w2); imagesetbrush($im, $brush); imageline($im, 100, 0, 0, 100, IMG_COLOR_STYLEDBRUSHED); imagejpeg($im); imagedestroy($im); ?>

Nota: This function was added in PHP 4.0.6

imagesetthickness

(PHP 4 >= 4.0.6, PHP 5)

imagesetthickness -- Set the thickness for line drawing

Description

bool imagesetthickness ( resource image, int thickness )

imagesetthickness() sets the thickness of the lines drawn when drawing rectangles, polygons, ellipses etc. etc. to thickness pixels. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Nota: This function requires GD 2.0.1 or later.

imagesettile

(PHP 4 >= 4.0.6, PHP 5)

imagesettile -- Set the tile image for filling

Description

bool imagesettile ( resource image, resource tile )

imagesettile() sets the tile image to be used by all region filling functions (such as imagefill() and imagefilledpolygon()) when filling with the special color IMG_COLOR_TILED.

A tile is an image used to fill an area with a repeated pattern. Any GD image can be used as a tile, and by setting the transparent color index of the tile image with imagecolortransparent(), a tile allows certain parts of the underlying area to shine through can be created.

Nota: You need not take special action when you are finished with a tile, but if you destroy the tile image, you must not use the IMG_COLOR_TILED color until you have set a new tile image!

imagestring

(PHP 3, PHP 4, PHP 5)

imagestring -- Draw a string horizontally

Description

bool imagestring ( resource image, int font, int x, int y, string s, int col )

imagestring() draws the string s in the image identified by image with the upper-left corner at coordinates x, y (top left is 0, 0) in color col. If font is 1, 2, 3, 4 or 5, a built-in font is used.

Esempio 1. imagestring() example
<?php // create a 100*30 image $im = imagecreatetruecolor(100, 30); // white background and blue text $bg = imagecolorallocate($im, 255, 255, 255); $textcolor = imagecolorallocate($im, 0, 0, 255); // write the string at the top left imagestring($im, 5, 0, 0, "Hello world!", $textcolor); // output the image header("Content-type: image/jpeg"); imagejpeg($im); ?>

See also imageloadfont(), and imagettftext().

imagestringup

(PHP 3, PHP 4, PHP 5)

imagestringup -- Draw a string vertically

Description

dither indicates if the image should be dithered - if it is TRUE then dithering will be used which will result in a more speckled image but with better color approximation.

ncolors sets the maximum number of colors that should be retained in the palette.

Nota: This function requires GD 2.0.1 or later.

imagettfbbox

(PHP 3 >= 3.0.1, PHP 4, PHP 5)

imagettfbbox -- Give the bounding box of a text using TrueType fonts

Description

array imagettfbbox ( float size, float angle, string fontfile, string text )

This function calculates and returns the bounding box in pixels for a TrueType text.

size: The font size in pixels.
angle: Angle in degrees in which text will be measured.
fontfile: The name of the TrueType font file (can be a URL). Depending on which version of the GD library that PHP is using, it may attempt to search for files that do not begin with a leading '/' by appending '.ttf' to the filename and searching along a library-defined font path.
text: The string to be measured.

imagettfbbox() returns an array with 8 elements representing four points making the bounding box of the text:

0	lower left corner, X position
1	lower left corner, Y position
2	lower right corner, X position
3	lower right corner, Y position
4	upper right corner, X position
5	upper right corner, Y position
6	upper left corner, X position
7	upper left corner, Y position

The points are relative to the text regardless of the angle, so "upper left" means in the top left-hand corner seeing the text horizontally.

This function requires both the GD library and the FreeType library.

imagettftext

(PHP 3, PHP 4, PHP 5)

imagettftext -- Write text to the image using TrueType fonts

Description

array imagettftext ( resource image, float size, float angle, int x, int y, int color, string fontfile, string text )

image

The image resource. See imagecreatetruecolor().

size

The font size. Depending on your version of GD, this should be specified as the pixel size (GD1) or point size (GD2).

angle

The angle in degrees, with 0 degrees being left-to-right reading text. Higher values represent a counter-clockwise rotation. For example, a value of 90 would result in bottom-to-top reading text.

x

The coordinates given by x and y will define the basepoint of the first character (roughly the lower-left corner of the character). This is different from the imagestring(), where x and y define the upper-left corner of the first character. For example, "top left" is 0, 0.

y

The y-ordinate. This sets the position of the fonts baseline, not the very bottom of the character.

color

The color index. Using the negative of a color index has the effect of turning off antialiasing. See imagecolorallocate().

fontfile

The path to the TrueType font you wish to use.

Depending on which version of the GD library PHP is using, when fontfile does not begin with a leading / then .ttf will be appended to the filename and the library will attempt to search for that filename along a library-defined font path.

When using versions of the GD library lower than 2.0.18, a space character, rather than a semicolon, was used as the 'path separator' for different font files. Unintentional use of this feature will result in the warning message: Warning: Could not find/open font. For these affected versions, the only solution is moving the font to a path which does not contain spaces.

In many cases where a font resides in the same directory as the script using it the following trick will alleviate any include problems.
<?php // Set the enviroment variable for GD putenv('GDFONTPATH=' . realpath('.')); // Name the font to be used (note the lack of the .ttf extension) $font = 'SomeFont'; ?>

text

The text string.

May include decimal numeric character references (of the form: €) to access characters in a font beyond position 127. Strings in UTF-8 encoding can be passed directly.

If a character is used in the string which is not supported by the font, a hollow rectangle will replace the character.

imagettftext() returns an array with 8 elements representing four points making the bounding box of the text. The order of the points is lower left, lower right, upper right, upper left. The points are relative to the text regardless of the angle, so "upper left" means in the top left-hand corner when you see the text horizontally.

Esempio 1. imagettftext() example
This example script will produce a white PNG 400x30 pixels, with the words "Testing..." in black (with grey shadow), in the font Arial.
<?php // Set the content-type header("Content-type: image/png"); // Create the image $im = imagecreatetruecolor(400, 30); // Create some colors $white = imagecolorallocate($im, 255, 255, 255); $grey = imagecolorallocate($im, 128, 128, 128); $black = imagecolorallocate($im, 0, 0, 0); // The text to draw $text = 'Testing...'; // Replace path by your own font path $font = 'arial.ttf'; // Add some shadow to the text imagettftext($im, 20, 0, 11, 21, $grey, $font, $text); // Add the text imagettftext($im, 20, 0, 10, 20, $black, $font, $text); // Using imagepng() results in clearer text compared with imagejpeg() imagepng($im); imagedestroy($im); ?>

This function requires both the GD library and the FreeType library.

imagetypes

bool imagexbm ( resource image, string filename [, int foreground] )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Nota: Questa funzione è disponibile soltanto se il PHP ` compilato con la libreria GD allegata.

iptcembed

(PHP 3 >= 3.0.7, PHP 4, PHP 5)

iptcembed -- Embed binary IPTC data into a JPEG image

Description

mixed iptcembed ( string iptcdata, string jpeg_file_name [, int spool] )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

iptcparse

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

iptcparse -- Parse a binary IPTC http://www.iptc.org/ block into single tags.

Description

array iptcparse ( string iptcblock )

This function parses a binary IPTC block into its single tags. It returns an array using the tagmarker as an index and the value as the value. It returns FALSE on error or if no IPTC data was found. See getimagesize() for a sample.

jpeg2wbmp

(PHP 4 >= 4.0.5, PHP 5)

jpeg2wbmp -- Convert JPEG image file to WBMP image file

Description

int jpeg2wbmp ( string jpegname, string wbmpname, int d_height, int d_width, int threshold )

Converts the jpegname JPEG file to WBMP format, and saves it as wbmpname. With the d_height and d_width you specify the height and width of the destination image.

Nota: JPEG support is only available if PHP was compiled against GD-1.8 or later.

Nota: WBMP support is only available if PHP was compiled against GD-1.8 or later.

png2wbmp

(PHP 4 >= 4.0.5, PHP 5)

png2wbmp -- Convert PNG image file to WBMP image file

Description

int png2wbmp ( string pngname, string wbmpname, int d_height, int d_width, int threshold )

Converts the pngname PNG file to WBMP format, and saves it as wbmpname. With the d_height and d_width you specify the height and width of the destination image.

Nota: WBMP support is only available if PHP was compiled against GD-1.8 or later.

LVII. IMAP, POP3 and NNTP Functions

Introduzione

These functions are not limited to the IMAP protocol, despite their name. The underlying c-client library also supports NNTP, POP3 and local mailbox access methods.

Requisiti

This extension requires the c-client library to be installed. Grab the latest version from ftp://ftp.cac.washington.edu/imap/ and compile it.

It's important that you do not copy the IMAP source files directly into the system include directory as there may be conflicts. Instead, create a new directory inside the system include directory, such as /usr/local/imap-2000b/ (location and name depend on your setup and IMAP version), and inside this new directory create additional directories named lib/ and include/. From the c-client directory from your IMAP source tree, copy all the *.h files into include/ and all the *.c files into lib/. Additionally when you compiled IMAP, a file named c-client.a was created. Also put this in the lib/ directory but rename it as libc-client.a.

Nota: To build the c-client library with SSL or/and Kerberos support read the docs supplied with the package.

Nota: In Mandrake Linux, the IMAP library (libc-client.a) is compiled without Kerberos support. A separate version with SSL (client-PHP4.a) is installed. The library must be recompiled in order to add Kerberos support.

Installazione

To get these functions to work, you have to compile PHP with --with-imap[=DIR], where DIR is the c-client install prefix. From our example above, you would use --with-imap=/usr/local/imap-2000b. This location depends on where you created this directory according to the description above. Windows users may include the php_imap.dll DLL in php.ini. IMAP is not supported on systems earlier that Windows 2000. This is because it uses encryption functions in order to enable SSL connections to the mail servers.

Nota: Depending how the c-client was configured, you might also need to add --with-imap-ssl=/path/to/openssl/ and/or --with-kerberos=/path/to/kerberos into the PHP configure line.

Avvertimento

Il modulo IMAP non può essere utilizzato in congiunzione con i moduli recode, YAZ oppure Cyrus. Poichè questi moduli condividono i medesimi simboli interni.

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Tipi di risorse

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

NIL (integer)
OP_DEBUG (integer)
OP_READONLY (integer): Open mailbox read-only
OP_ANONYMOUS (integer): Don't use or update a .newsrc for news (NNTP only)
OP_SHORTCACHE (integer)
OP_SILENT (integer)
OP_PROTOTYPE (integer)
OP_HALFOPEN (integer): For IMAP and NNTP names, open a connection but don't open a mailbox.
OP_EXPUNGE (integer)
OP_SECURE (integer)
CL_EXPUNGE (integer): silently expunge the mailbox before closing when calling imap_close()
FT_UID (integer): The parameter is a UID
FT_PEEK (integer): Do not set the \Seen flag if not already set
FT_NOT (integer)
FT_INTERNAL (integer): The return string is in internal format, will not canonicalize to CRLF.
FT_PREFETCHTEXT (integer)
ST_UID (integer): The sequence argument contains UIDs instead of sequence numbers
ST_SILENT (integer)
ST_SET (integer)
CP_UID (integer): the sequence numbers contain UIDS
CP_MOVE (integer): Delete the messages from the current mailbox after copying with imap_mail_copy()
SE_UID (integer): Return UIDs instead of sequence numbers
SE_FREE (integer)
SE_NOPREFETCH (integer): Don't prefetch searched messages
SO_FREE (integer)
SO_NOSERVER (integer)
SA_MESSAGES (integer)
SA_RECENT (integer)
SA_UNSEEN (integer)
SA_UIDNEXT (integer)
SA_UIDVALIDITY (integer)
SA_ALL (integer)
LATT_NOINFERIORS (integer): This mailbox has no "children" (there are no mailboxes below this one).
LATT_NOSELECT (integer): This is only a container, not a mailbox - you cannot open it.
LATT_MARKED (integer): This mailbox is marked. Only used by UW-IMAPD.
LATT_UNMARKED (integer): This mailbox is not marked. Only used by UW-IMAPD.
SORTDATE (integer): Sort criteria for imap_sort(): message Date
SORTARRIVAL (integer): Sort criteria for imap_sort(): arrival date
SORTFROM (integer): Sort criteria for imap_sort(): mailbox in first From address
SORTSUBJECT (integer): Sort criteria for imap_sort(): message subject
SORTTO (integer): Sort criteria for imap_sort(): mailbox in first To address
SORTCC (integer): Sort criteria for imap_sort(): mailbox in first cc address
SORTSIZE (integer): Sort criteria for imap_sort(): size of message in octets
TYPETEXT (integer)
TYPEMULTIPART (integer)
TYPEMESSAGE (integer)
TYPEAPPLICATION (integer)
TYPEAUDIO (integer)
TYPEIMAGE (integer)
TYPEVIDEO (integer)
TYPEOTHER (integer)
ENC7BIT (integer)
ENC8BIT (integer)
ENCBINARY (integer)
ENCBASE64 (integer)
ENCQUOTEDPRINTABLE (integer)
ENCOTHER (integer)

Vedere anche:

This document can't go into detail on all the topics touched by the provided functions. Further information is provided by the documentation of the c-client library source (docs/internal.txt). and the following RFC documents:

RFC2821: Simple Mail Transfer Protocol (SMTP).
RFC2822: Standard for ARPA internet text messages.
RFC2060: Internet Message Access Protocol (IMAP) Version 4rev1.
RFC1939: Post Office Protocol Version 3 (POP3).
RFC977: Network News Transfer Protocol (NNTP).
RFC2076: Common Internet Message Headers.
RFC2045 , RFC2046 , RFC2047 , RFC2048 & RFC2049: Multipurpose Internet Mail Extensions (MIME).

A detailed overview is also available in the books Programming Internet Email by David Wood and Managing IMAP by Dianna Mullet & Kevin Mullet.

Sommario
imap_8bit -- Convert an 8bit string to a quoted-printable string
imap_alerts -- This function returns all IMAP alert messages (if any) that have occurred during this page request or since the alert stack was reset
imap_append -- Append a string message to a specified mailbox
imap_base64 -- Decode BASE64 encoded text
imap_binary -- Convert an 8bit string to a base64 string
imap_body -- Read the message body
imap_bodystruct -- Read the structure of a specified body section of a specific message
imap_check -- Check current mailbox
imap_clearflag_full -- Clears flags on messages
imap_close -- Close an IMAP stream
imap_createmailbox -- Create a new mailbox
imap_delete -- Mark a message for deletion from current mailbox
imap_deletemailbox -- Delete a mailbox
imap_errors -- This function returns all of the IMAP errors (if any) that have occurred during this page request or since the error stack was reset
imap_expunge -- Delete all messages marked for deletion
imap_fetch_overview -- Read an overview of the information in the headers of the given message
imap_fetchbody -- Fetch a particular section of the body of the message
imap_fetchheader -- Returns header for a message
imap_fetchstructure -- Read the structure of a particular message
imap_get_quota -- Retrieve the quota level settings, and usage statics per mailbox
imap_get_quotaroot -- Retrieve the quota settings per user
imap_getacl -- Gets the ACL for a given mailbox
imap_getmailboxes -- Read the list of mailboxes, returning detailed information on each one
imap_getsubscribed -- List all the subscribed mailboxes
imap_header -- Alias di imap_headerinfo()
imap_headerinfo -- Read the header of the message
imap_headers -- Returns headers for all messages in a mailbox
imap_last_error -- This function returns the last IMAP error (if any) that occurred during this page request
imap_list -- Read the list of mailboxes
imap_listmailbox -- Alias di imap_list()
imap_listscan -- Read the list of mailboxes, takes a string to search for in the text of the mailbox
imap_listsubscribed -- Alias di imap_lsub()
imap_lsub -- List all the subscribed mailboxes
imap_mail_compose -- Create a MIME message based on given envelope and body sections
imap_mail_copy -- Copy specified messages to a mailbox
imap_mail_move -- Move specified messages to a mailbox
imap_mail -- Send an email message
imap_mailboxmsginfo -- Get information about the current mailbox
imap_mime_header_decode -- Decode MIME header elements
imap_msgno -- This function returns the message sequence number for the given UID
imap_num_msg -- Gives the number of messages in the current mailbox
imap_num_recent -- Gives the number of recent messages in current mailbox
imap_open -- Open an IMAP stream to a mailbox
imap_ping -- Check if the IMAP stream is still active
imap_qprint -- Convert a quoted-printable string to an 8 bit string
imap_renamemailbox -- Rename an old mailbox to new mailbox
imap_reopen -- Reopen IMAP stream to new mailbox
imap_rfc822_parse_adrlist -- Parses an address string
imap_rfc822_parse_headers -- Parse mail headers from a string
imap_rfc822_write_address -- Returns a properly formatted email address given the mailbox, host, and personal info
imap_scanmailbox -- Alias di imap_listscan()
imap_search -- This function returns an array of messages matching the given search criteria
imap_set_quota -- Sets a quota for a given mailbox
imap_setacl -- Sets the ACL for a giving mailbox
imap_setflag_full -- Sets flags on messages
imap_sort -- Sort an array of message headers
imap_status -- This function returns status information on a mailbox other than the current one
imap_subscribe -- Subscribe to a mailbox
imap_thread -- Returns a tree of threaded message
imap_timeout -- Set or fetch imap timeout
imap_uid -- This function returns the UID for the given message sequence number
imap_undelete -- Unmark the message which is marked deleted
imap_unsubscribe -- Unsubscribe from a mailbox
imap_utf7_decode -- Decodes a modified UTF-7 encoded string
imap_utf7_encode -- Converts ISO-8859-1 string to modified UTF-7 text
imap_utf8 -- Converts MIME-encoded text to UTF-8

imap_8bit

(PHP 3, PHP 4, PHP 5)

imap_8bit -- Convert an 8bit string to a quoted-printable string

Description

string imap_8bit ( string string )

string imap_binary ( string string )

Convert an 8bit string to a base64 string (according to RFC2045, Section 6.8).

Returns a base64 string.

imap_body

(PHP 3, PHP 4, PHP 5)

imap_body -- Read the message body

Description

string imap_body ( resource imap_stream, int msg_number [, int options] )

imap_body() returns the body of the message, numbered msg_number in the current mailbox.

The optional options are a bit mask with one or more of the following:

FT_UID - The msg_number is a UID
FT_PEEK - Do not set the \Seen flag if not already set
FT_INTERNAL - The return string is in internal format, will not canonicalize to CRLF.

imap_body() will only return a verbatim copy of the message body. To extract single parts of a multipart MIME-encoded message you have to use imap_fetchstructure() to analyze its structure and imap_fetchbody() to extract a copy of a single body component.

imap_bodystruct

(PHP 3 >= 3.0.4, PHP 4, PHP 5)

imap_bodystruct -- Read the structure of a specified body section of a specific message

Description

object imap_bodystruct ( resource stream_id, int msg_no, string section )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

imap_check

(PHP 3, PHP 4, PHP 5)

imap_check -- Check current mailbox

Description

object imap_check ( resource imap_stream )

Returns information about the current mailbox. Returns FALSE on failure.

The imap_check() function checks the current mailbox status on the server and returns the information in an object with following properties:

Date - current system time formatted according to RFC822
Driver - protocol used to access this mailbox: POP3, IMAP, NNTP
Mailbox - the mailbox name
Nmsgs - number of messages in the mailbox
Recent - number of recent messages in the mailbox

Esempio 1. imap_check() example
<?php $imap_obj = imap_check($imap_stream); var_dump($imap_obj); ?>
this will output :
object(stdClass)(5) { ["Date"]=> string(37) "Wed, 10 Dec 2003 17:56:54 +0100 (CET)" ["Driver"]=> string(4) "imap" ["Mailbox"]=> string(54) "{www.example.com:143/imap/user="foo@example.com"}INBOX" ["Nmsgs"]=> int(1) ["Recent"]=> int(0) }

imap_clearflag_full

(PHP 3 >= 3.0.3, PHP 4, PHP 5)

imap_clearflag_full -- Clears flags on messages

Description

bool imap_clearflag_full ( resource stream, string sequence, string flag [, string options] )

This function causes a store to delete the specified flag to the flags set for the messages in the specified sequence. The flags which you can unset are "\\Seen", "\\Answered", "\\Flagged", "\\Deleted", and "\\Draft" (as defined by RFC2060). Restituisce TRUE in caso di successo, FALSE in caso di fallimento..

options are a bit mask and may contain the single option:

ST_UID - The sequence argument contains UIDs instead of sequence numbers

Description

bool imap_delete ( int imap_stream, int msg_number [, int options] )

Returns TRUE.

imap_delete() marks messages listed in msg_number for deletion. The optional flags parameter only has a single option, FT_UID, which tells the function to treat the msg_number argument as a UID. Messages marked for deletion will stay in the mailbox until either imap_expunge() is called or imap_close() is called with the optional parameter CL_EXPUNGE.

Nota: POP3 mailboxes do not have their message flags saved between connections, so imap_expunge() must be called during the same connection in order for messages marked for deletion to actually be purged.

Esempio 1. imap_delete() example
<?php $mbox = imap_open("{your.imap.host}INBOX", "username", "password") or die("Can't connect: " . imap_last_error()); $check = imap_mailboxmsginfo($mbox); echo "Messages before delete: " . $check->Nmsgs . "<br />\n"; imap_delete($mbox, 1); $check = imap_mailboxmsginfo($mbox); echo "Messages after delete: " . $check->Nmsgs . "<br />\n"; imap_expunge($mbox); $check = imap_mailboxmsginfo($mbox); echo "Messages after expunge: " . $check->Nmsgs . "<br />\n"; imap_close($mbox); ?>

imap_deletemailbox

(PHP 3, PHP 4, PHP 5)

imap_deletemailbox -- Delete a mailbox

Description

bool imap_deletemailbox ( resource imap_stream, string mbox )

imap_deletemailbox() deletes the specified mailbox (see imap_open() for the format of mbox names).

Restituisce TRUE in caso di successo, FALSE in caso di fallimento..

See also imap_createmailbox(), imap_renamemailbox(), and imap_open() for the format of mbox.

imap_errors

(PHP 3 >= 3.0.12, PHP 4, PHP 5)

imap_errors -- This function returns all of the IMAP errors (if any) that have occurred during this page request or since the error stack was reset

Description

array imap_errors ( void )

This function returns an array of all of the IMAP error messages generated since the last imap_errors() call, or the beginning of the page. When imap_errors() is called, the error stack is subsequently cleared.

imap_expunge

(PHP 3, PHP 4, PHP 5)

imap_expunge -- Delete all messages marked for deletion

Description

This function fetches all the structured information for a given message. The optional options parameter only has a single option, FT_UID, which tells the function to treat the msg_number argument as a UID. The returned object includes the envelope, internal date, size, flags and body structure along with a similar object for each mime attachment. The structure of the returned objects is as follows:

Tabella 1. Returned Objects for imap_fetchstructure()

type	Primary body type
encoding	Body transfer encoding
ifsubtype	`TRUE` if there is a subtype string
subtype	MIME subtype
ifdescription	`TRUE` if there is a description string
description	Content description string
ifid	`TRUE` if there is an identification string
id	Identification string
lines	Number of lines
bytes	Number of bytes
ifdisposition	`TRUE` if there is a disposition string
disposition	Disposition string
ifdparameters	`TRUE` if the dparameters array exists
dparameters	An array of objects where each object has an "attribute" and a "value" property corresponding to the parameters on the Content-disposition MIMEheader.
ifparameters	`TRUE` if the parameters array exists
parameters	An array of objects where each object has an "attribute" and a "value" property.
parts	An array of objects identical in structure to the top-level object, each of which corresponds to a MIME body part.

Tabella 2. Primary body type

0	text
1	multipart
2	message
3	application
4	audio
5	image
6	video
7	other

Tabella 3. Transfer encodings

0	7BIT
1	8BIT
2	BINARY
3	BASE64
4	QUOTED-PRINTABLE
5	OTHER

imap_get_quota

(PHP 4 >= 4.0.5, PHP 5)

imap_get_quota -- Retrieve the quota level settings, and usage statics per mailbox

Description

array imap_get_quota ( resource imap_stream, string quota_root )

Returns an array with integer values limit and usage for the given mailbox. The value of limit represents the total amount of space allowed for this mailbox. The usage value represents the mailboxes current level of capacity. Will return FALSE in the case of failure.

This function is currently only available to users of the c-client2000 or greater library.

NOTE: For this function to work, the mail stream is required to be opened as the mail-admin user. For a non-admin user version of this function, please see the imap_get_quotaroot() function of PHP.

imap_stream should be the value returned from an imap_open() call. NOTE: This stream is required to be opened as the mail admin user for the get_quota function to work. quota_root should normally be in the form of user.name where name is the mailbox you wish to retrieve information about.

Esempio 1. imap_get_quota() example
<?php $mbox = imap_open("{your.imap.host}", "mailadmin", "password", OP_HALFOPEN) or die("can't connect: " . imap_last_error()); $quota_value = imap_get_quota($mbox, "user.kalowsky"); if (is_array($quota_value)) { echo "Usage level is: " . $quota_value['usage']; echo "Limit level is: " . $quota_value['limit']; } imap_close($mbox); ?>

As of PHP 4.3, the function more properly reflects the functionality as dictated by the RFC 2087. The array return value has changed to support an unlimited number of returned resources (i.e. messages, or sub-folders) with each named resource receiving an individual array key. Each key value then contains an another array with the usage and limit values within it. The example below shows the updated returned output.

For backwards compatibility reasons, the original access methods are still available for use, although it is suggested to update.

Esempio 2. imap_get_quota() 4.3 or greater example
<?php $mbox = imap_open("{your.imap.host}", "mailadmin", "password", OP_HALFOPEN) or die("can't connect: " . imap_last_error()); $quota_values = imap_get_quota($mbox, "user.kalowsky"); if (is_array($quota_values)) { $storage = $quota_values['STORAGE']; echo "STORAGE usage level is: " . $storage['usage']; echo "STORAGE limit level is: " . $storage['limit']; $message = $quota_values['MESSAGE']; echo "MESSAGE usage level is: " . $message['usage']; echo "MESSAGE limit is: " . $message['limit']; /* ... */ } imap_close($mbox); ?>

imap_get_quotaroot

(PHP 4 >= 4.3.0, PHP 5)

imap_get_quotaroot -- Retrieve the quota settings per user

Description

array imap_get_quotaroot ( resource imap_stream, string quota_root )

Returns an array of integer values pertaining to the specified user mailbox. All values contain a key based upon the resource name, and a corresponding array with the usage and limit values within.

The limit value represents the total amount of space allowed for this user's total mailbox usage. The usage value represents the user's current total mailbox capacity. This function will return FALSE in the case of call failure, and an array of information about the connection upon an un-parsable response from the server.

This function is currently only available to users of the c-client2000 or greater library.

(PHP 3, PHP 4, PHP 5)

imap_headerinfo -- Read the header of the message

Description

object imap_headerinfo ( resource imap_stream, int msg_number [, int fromlength [, int subjectlength [, string defaulthost]]] )

array imap_list ( resource imap_stream, string ref, string pattern )

Returns an array containing the names of the mailboxes. See imap_getmailboxes() for a description of ref and pattern.

Esempio 1. imap_list() example
<?php $mbox = imap_open("{your.imap.host}", "username", "password", OP_HALFOPEN) or die("can't connect: " . imap_last_error()); $list = imap_list($mbox, "{your.imap.host}", "*"); if (is_array($list)) { foreach ($list as $val) { echo imap_utf7_decode($val) . "<br />\n"; } } else { echo "imap_list failed: " . imap_last_error() . "\n"; } imap_close($mbox); ?>

imap_listmailbox

(PHP 3, PHP 4, PHP 5)

imap_listmailbox -- Alias di imap_list()

Descrizione

This function is an alias of: imap_list().

imap_listscan

(no version information, might be only in CVS)

imap_listscan -- Read the list of mailboxes, takes a string to search for in the text of the mailbox

Description

array imap_listscan ( resource imap_stream, string ref, string pattern, string content )

Returns an array containing the names of the mailboxes that have content in the text of the mailbox.

This function is similar to imap_listmailbox(), but it will additionally check for the presence of the string content inside the mailbox data.

See imap_getmailboxes() for a description of ref and pattern.

imap_listsubscribed

(PHP 3, PHP 4, PHP 5)

imap_listsubscribed -- Alias di imap_lsub()

bool imap_mail_copy ( resource imap_stream, string msglist, string mbox [, int options] )

Copies mail messages specified by msglist to specified mailbox. Restituisce TRUE in caso di successo, FALSE in caso di fallimento..

msglist is a range not just message numbers (as described in RFC2060).

options is a bitmask of one or more of

CP_UID - the sequence numbers contain UIDS
CP_MOVE - Delete the messages from the current mailbox after copying

imap_mail_move

(PHP 3, PHP 4, PHP 5)

imap_mail_move -- Move specified messages to a mailbox

Description

bool imap_mail_move ( resource imap_stream, string msglist, string mbox [, int options] )

Moves mail messages specified by msglist to specified mailbox mbox. Restituisce TRUE in caso di successo, FALSE in caso di fallimento..

msglist is a range not just message numbers (as described in RFC2060).

options is a bitmask and may contain the single option:

CP_UID - the sequence numbers contain UIDS

imap_mail

(PHP 3 >= 3.0.14, PHP 4, PHP 5)

imap_mail -- Send an email message

Description

bool imap_mail ( string to, string subject, string message [, string additional_headers [, string cc [, string bcc [, string rpath]]]] )

This function allows sending of emails with correct handling of Cc and Bcc receivers. Restituisce TRUE in caso di successo, FALSE in caso di fallimento..

The parameters to, cc and bcc are all strings and are all parsed as rfc822 address lists.

The receivers specified in bcc will get the mail, but are excluded from the headers.

Use the rpath parameter to specify return path. This is useful when using PHP as a mail client for multiple users.

imap_mailboxmsginfo

(PHP 3 >= 3.0.2, PHP 4, PHP 5)

imap_mailboxmsginfo -- Get information about the current mailbox

Description

object imap_mailboxmsginfo ( resource imap_stream )

Returns information about the current mailbox. Returns FALSE on failure.

The imap_mailboxmsginfo() function checks the current mailbox status on the server. It is similar to imap_status(), but will additionally sum up the size of all messages in the mailbox, which will take some additional time to execute. It returns the information in an object with following properties.

Tabella 1. Mailbox properties

Date	date of last change
Driver	driver
Mailbox	name of the mailbox
Nmsgs	number of messages
Recent	number of recent messages
Unread	number of unread messages
Deleted	number of deleted messages
Size	mailbox size

Esempio 1. imap_mailboxmsginfo() example
<?php $mbox = imap_open("{your.imap.host}INBOX", "username", "password") or die("can't connect: " . imap_last_error()); $check = imap_mailboxmsginfo($mbox); if ($check) { echo "Date: " . $check->Date . "<br />\n" ; echo "Driver: " . $check->Driver . "<br />\n" ; echo "Mailbox: " . $check->Mailbox . "<br />\n" ; echo "Messages: " . $check->Nmsgs . "<br />\n" ; echo "Recent: " . $check->Recent . "<br />\n" ; echo "Unread: " . $check->Unread . "<br />\n" ; echo "Deleted: " . $check->Deleted . "<br />\n" ; echo "Size: " . $check->Size . "<br />\n" ; } else { echo "imap_check() failed: " . imap_last_error() . "<br />\n"; } imap_close($mbox); ?>

imap_mime_header_decode

(PHP 3 >= 3.0.17, PHP 4, PHP 5)

imap_mime_header_decode -- Decode MIME header elements

Description

array imap_mime_header_decode ( string text )

imap_mime_header_decode() function decodes MIME message header extensions that are non ASCII text (see RFC2047). The decoded elements are returned in an array of objects, where each object has two properties, "charset" and "text". If the element hasn't been encoded, and in other words is in plain US-ASCII,the "charset" property of that element is set to "default".

int imap_num_recent ( resource imap_stream )

Returns the number of recent messages in the current mailbox.

See also: imap_num_msg() and imap_status().

imap_open

(PHP 3, PHP 4, PHP 5)

imap_open -- Open an IMAP stream to a mailbox

Description

resource imap_open ( string mailbox, string username, string password [, int options] )

Returns an IMAP stream on success and FALSE on error. This function can also be used to open streams to POP3 and NNTP servers, but some functions and features are only available on IMAP servers.

A mailbox name consists of a server part and a mailbox path on this server. The special name INBOX stands for the current users personal mailbox. The server part, which is enclosed in '{' and '}', consists of the servers name or ip address, an optional port (prefixed by ':'), and an optional protocol specification (prefixed by '/'). The server part is mandatory in all mailbox parameters. Mailbox names that contain international characters besides those in the printable ASCII space have to be encoded with imap_utf7_encode().

All names which start with { are remote names, and are in the form "{" remote_system_name [":" port] [flags] "}" [mailbox_name] where:

remote_system_name - Internet domain name or bracketed IP address of server.
port - optional TCP port number, default is the default port for that service
flags - optional flags, see following table.
mailbox_name - remote mailbox name, default is INBOX

Tabella 1. Optional flags for names

Flag	Description
`/service=`service	mailbox access service, default is "imap"
`/user=`user	remote user name for login on the server
`/authuser=`user	remote authentication user; if specified this is the user name whose password is used (e.g. administrator)
`/anonymous`	remote access as anonymous user
`/debug`	record protocol telemetry in application's debug log
`/secure`	do not transmit a plaintext password over the network
`/imap`, `/imap2`, `/imap2bis`, `/imap4`, `/imap4rev1`	equivalent to /service=imap
`/pop3`	equivalent to /service=pop3
`/nntp`	equivalent to /service=nntp
`/norsh`	do not use rsh or ssh to establish a preauthenticated IMAP session
`/ssl`	use the Secure Socket Layer to encrypt the session
`/validate-cert`	validate certificates from TLS/SSL server (this is the default behavior)
`/novalidate-cert`	do not validate certificates from TLS/SSL server, needed if server uses self-signed certificates
`/tls`	force use of start-TLS to encrypt the session, and reject connection to servers that do not support it
`/notls`	do not do start-TLS to encrypt the session, even with servers that support it
`/readonly`	request read-only mailbox open (IMAP only; ignored on NNTP, and an error with SMTP and POP3)

The options are a bit mask with one or more of the following:

OP_READONLY - Open mailbox read-only
OP_ANONYMOUS - Don't use or update a .newsrc for news (NNTP only)
OP_HALFOPEN - For IMAP and NNTP names, open a connection but don't open a mailbox.
CL_EXPUNGE - Expunge mailbox automatically upon mailbox close (see also imap_delete() and imap_expunge())
OP_DEBUG - Debug protocol negotiations
OP_SHORTCACHE - Short (elt-only) caching
OP_SILENT - Don't pass up events (internal use)
OP_PROTOTYPE - Return driver prototype
OP_EXPUNGE - Silently expunge recycle stream
OP_SECURE - Don't do non-secure authentication

Esempio 1. Different use of imap_open()
<?php // To connect to an IMAP server running on port 143 on the local machine, // do the following: $mbox = imap_open("{localhost:143}INBOX", "user_id", "password"); // To connect to a POP3 server on port 110 on the local server, use: $mbox = imap_open ("{localhost:110/pop3}INBOX", "user_id", "password"); // To connect to an SSL IMAP or POP3 server, add /ssl after the protocol // specification: $mbox = imap_open ("{localhost:993/imap/ssl}INBOX", "user_id", "password"); // To connect to an SSL IMAP or POP3 server with a self-signed certificate, // add /ssl/novalidate-cert after the protocol specification: $mbox = imap_open ("{localhost:995/pop3/ssl/novalidate-cert}", "user_id", "password"); // To connect to an NNTP server on port 119 on the local server, use: $nntp = imap_open ("{localhost:119/nntp}comp.test", "", ""); // To connect to a remote server replace "localhost" with the name or the // IP address of the server you want to connect to. ?>

Esempio 2. imap_open() example
<?php $mbox = imap_open("{your.imap.host:143}", "username", "password"); echo "<h1>Mailboxes</h1>\n"; $folders = imap_listmailbox($mbox, "{your.imap.host:143}", "*"); if ($folders == false) { echo "Call failed<br />\n"; } else { foreach ($folders as $val) { echo $val . "<br />\n"; } } echo "<h1>Headers in INBOX</h1>\n"; $headers = imap_headers($mbox); if ($headers == false) { echo "Call failed<br />\n"; } else { foreach ($headers as $val) { echo $val . "<br />\n"; } } imap_close($mbox); ?>

imap_ping

(PHP 3, PHP 4, PHP 5)

imap_ping -- Check if the IMAP stream is still active

Description

bool imap_ping ( resource imap_stream )

Returns TRUE if the stream is still alive, FALSE otherwise.

imap_ping() pings the stream to see if it's still active. It may discover new mail; this is the preferred method for a periodic "new mail check" as well as a "keep alive" for servers which have inactivity timeout.

Esempio 1. imap_ping() Example
<?php $imap = imap_open("{your.imap.host}", "mailadmin", "password"); // after some sleeping if (!imap_ping($imap)) { // do some stuff to reconnect } ?>

imap_qprint

(PHP 3, PHP 4, PHP 5)

imap_qprint -- Convert a quoted-printable string to an 8 bit string

Description

string imap_qprint ( string string )

Convert a quoted-printable string to an 8 bit string (according to RFC2045, section 6.7).

imap_renamemailbox

(PHP 3, PHP 4, PHP 5)

imap_renamemailbox -- Rename an old mailbox to new mailbox

Description

bool imap_renamemailbox ( resource imap_stream, string old_mbox, string new_mbox )

This function renames on old mailbox to new mailbox (see imap_open() for the format of mbox names).

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

See also imap_createmailbox(), imap_deletemailbox(), and imap_open() for the format of mbox.

imap_reopen

(PHP 3, PHP 4, PHP 5)

imap_reopen -- Reopen IMAP stream to new mailbox

Description

bool imap_reopen ( resource imap_stream, string mailbox [, string options] )

This function reopens the specified stream to a new mailbox on an IMAP or NNTP server.

The options are a bit mask with one or more of the following:

OP_READONLY - Open mailbox read-only
OP_ANONYMOUS - Don't use or update a .newsrc for news (NNTP only)
OP_HALFOPEN - For IMAP and NNTP names, open a connection but don't open a mailbox.
CL_EXPUNGE - Expunge mailbox automatically upon mailbox close (see also imap_delete() and imap_expunge())

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

imap_rfc822_parse_adrlist

(PHP 3 >= 3.0.2, PHP 4, PHP 5)

imap_rfc822_parse_adrlist -- Parses an address string

Description

array imap_rfc822_parse_adrlist ( string address, string default_host )

This function parses the address string as defined in RFC2822 and for each address, returns an array of objects. The objects properties are:

mailbox - the mailbox name (username)
host - the host name
personal - the personal name
adl - at domain source route

Esempio 1. imap_rfc822_parse_adrlist() example
<?php $address_string = "Joe Doe <doe@example.com>, postmaster@example.com, root"; $address_array = imap_rfc822_parse_adrlist($address_string, "example.com"); if (!is_array($address_array) || count($address_array) < 1) { die("something is wrong\n"); } foreach ($address_array as $val) { echo "mailbox : " . $val->mailbox . "<br />\n"; echo "host : " . $val->host . "<br />\n"; echo "personal: " . $val->personal . "<br />\n"; echo "adl : " . $val->adl . "<br />\n"; } ?>

imap_rfc822_parse_headers

(PHP 4, PHP 5)

imap_rfc822_parse_headers -- Parse mail headers from a string

Description

object imap_rfc822_parse_headers ( string headers [, string defaulthost] )

This function returns an object of various header elements, similar to imap_header(), except without the flags and other elements that come from the IMAP server.

imap_rfc822_write_address

(PHP 3 >= 3.0.2, PHP 4, PHP 5)

imap_rfc822_write_address -- Returns a properly formatted email address given the mailbox, host, and personal info

Description

string imap_rfc822_write_address ( string mailbox, string host, string personal )

Returns a properly formatted email address as defined in RFC2822 given the mailbox, host, and personal info.

Esempio 1. imap_rfc822_write_address() example
<?php echo imap_rfc822_write_address("hartmut", "cvs.php.net", "Hartmut Holzgraefe") . "\n"; ?>

imap_scanmailbox

(PHP 3, PHP 4, PHP 5)

imap_scanmailbox -- Alias di imap_listscan()

Descrizione

This function is an alias of: imap_listscan().

imap_search

(PHP 3 >= 3.0.12, PHP 4, PHP 5)

imap_search -- This function returns an array of messages matching the given search criteria

Description

array imap_search ( resource imap_stream, string criteria [, int options [, string charset]] )

This function performs a search on the mailbox currently opened in the given imap stream. criteria is a string, delimited by spaces, in which the following keywords are allowed. Any multi-word arguments (e.g. FROM "joey smith") must be quoted.

ALL - return all messages matching the rest of the criteria
ANSWERED - match messages with the \\ANSWERED flag set
BCC "string" - match messages with "string" in the Bcc: field
BEFORE "date" - match messages with Date: before "date"
BODY "string" - match messages with "string" in the body of the message
CC "string" - match messages with "string" in the Cc: field
DELETED - match deleted messages
FLAGGED - match messages with the \\FLAGGED (sometimes referred to as Important or Urgent) flag set
FROM "string" - match messages with "string" in the From: field
KEYWORD "string" - match messages with "string" as a keyword
NEW - match new messages
OLD - match old messages
ON "date" - match messages with Date: matching "date"
RECENT - match messages with the \\RECENT flag set
SEEN - match messages that have been read (the \\SEEN flag is set)
SINCE "date" - match messages with Date: after "date"
SUBJECT "string" - match messages with "string" in the Subject:
TEXT "string" - match messages with text "string"
TO "string" - match messages with "string" in the To:
UNANSWERED - match messages that have not been answered
UNDELETED - match messages that are not deleted
UNFLAGGED - match messages that are not flagged
UNKEYWORD "string" - match messages that do not have the keyword "string"
UNSEEN - match messages which have not been read yet

For example, to match all unanswered messages sent by Mom, you'd use: "UNANSWERED FROM mom". Searches appear to be case insensitive. This list of criteria is from a reading of the UW c-client source code and may be incomplete or inaccurate (see also RFC2060, section 6.4.4).

Valid values for flags are SE_UID, which causes the returned array to contain UIDs instead of messages sequence numbers.

Parameter charset was added in PHP 4.3.3.

imap_set_quota

(PHP 4 >= 4.0.5, PHP 5)

imap_set_quota -- Sets a quota for a given mailbox

Description

bool imap_set_quota ( resource imap_stream, string quota_root, int quota_limit )

Sets an upper limit quota on a per mailbox basis. This function requires the imap_stream to have been opened as the mail administrator account. It will not work if opened as any other user.

This function is currently only available to users of the c-client2000 or greater library.

imap_stream is the stream pointer returned from a imap_open() call. This stream must be opened as the mail administrator, other wise this function will fail. quota_root is the mailbox to have a quota set. This should follow the IMAP standard format for a mailbox, 'user.name'. quota_limit is the maximum size (in KB) for the quota_root.

Returns TRUE on success and FALSE on error.

Esempio 1. imap_set_quota() example
<?php $mbox = imap_open("{your.imap.host:143}", "mailadmin", "password"); if (!imap_set_quota($mbox, "user.kalowsky", 3000)) { echo "Error in setting quota\n"; return; } imap_close($mbox); ?>

imap_setacl

(PHP 4 >= 4.1.0, PHP 5)

imap_setacl -- Sets the ACL for a giving mailbox

Description

bool imap_setacl ( resource stream_id, string mailbox, string id, string rights )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

This function is currently only available to users of the c-client2000 or greater library.

imap_setflag_full

(PHP 3 >= 3.0.3, PHP 4, PHP 5)

imap_setflag_full -- Sets flags on messages

Description

bool imap_setflag_full ( resource stream, string sequence, string flag [, string options] )

This function causes a store to add the specified flag to the flags set for the messages in the specified sequence.

The flags which you can set are "\\Seen", "\\Answered", "\\Flagged", "\\Deleted", and "\\Draft" (as defined by RFC2060).

options are a bit mask and may contain the single option:

ST_UID - The sequence argument contains UIDs instead of sequence numbers

Esempio 1. imap_setflag_full() example
<?php $mbox = imap_open("{your.imap.host:143}", "username", "password") or die("can't connect: " . imap_last_error()); $status = imap_setflag_full($mbox, "2,5", "\\Seen \\Flagged"); echo gettype($status) . "\n"; echo $status . "\n"; imap_close($mbox); ?>

imap_sort

(PHP 3 >= 3.0.3, PHP 4, PHP 5)

imap_sort -- Sort an array of message headers

Description

array imap_sort ( resource stream, int criteria, int reverse [, int options [, string search_criteria [, string charset]]] )

Returns an array of message numbers sorted by the given parameters.

Reverse is 1 for reverse-sorting.

Criteria can be one (and only one) of the following:

SORTDATE - message Date
SORTARRIVAL - arrival date
SORTFROM - mailbox in first From address
SORTSUBJECT - message subject
SORTTO - mailbox in first To address
SORTCC - mailbox in first cc address
SORTSIZE - size of message in octets

The flags are a bitmask of one or more of the following:

SE_UID - Return UIDs instead of sequence numbers
SE_NOPREFETCH - Don't prefetch searched messages

Parameter charset was added in PHP 4.3.3.

imap_status

(PHP 3 >= 3.0.4, PHP 4, PHP 5)

imap_status -- This function returns status information on a mailbox other than the current one

Description

object imap_status ( resource imap_stream, string mailbox, int options )

This function returns an object containing status information. Valid flags are:

SA_MESSAGES - set status->messages to the number of messages in the mailbox
SA_RECENT - set status->recent to the number of recent messages in the mailbox
SA_UNSEEN - set status->unseen to the number of unseen (new) messages in the mailbox
SA_UIDNEXT - set status->uidnext to the next uid to be used in the mailbox
SA_UIDVALIDITY - set status->uidvalidity to a constant that changes when uids for the mailbox may no longer be valid
SA_ALL - set all of the above

status->flags is also set, which contains a bitmask which can be checked against any of the above constants.

Esempio 1. imap_status() example
<?php $mbox = imap_open("{your.imap.host}", "username", "password", OP_HALFOPEN) or die("can't connect: " . imap_last_error()); $status = imap_status($mbox, "{your.imap.host}INBOX", SA_ALL); if ($status) { echo "Messages: " . $status->messages . "<br />\n"; echo "Recent: " . $status->recent . "<br />\n"; echo "Unseen: " . $status->unseen . "<br />\n"; echo "UIDnext: " . $status->uidnext . "<br />\n"; echo "UIDvalidity:" . $status->uidvalidity . "<br />\n"; } else { echo "imap_status failed: " . imap_last_error() . "\n"; } imap_close($mbox); ?>

imap_subscribe

(PHP 3, PHP 4, PHP 5)

imap_subscribe -- Subscribe to a mailbox

Description

bool imap_subscribe ( resource imap_stream, string mbox )

Subscribe to a new mailbox.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

imap_thread

(PHP 4 >= 4.1.0, PHP 5)

imap_thread -- Returns a tree of threaded message

Description

array imap_thread ( resource stream_id [, int options] )

imap_thread() returns an associative array containing a tree of messages threaded by REFERENCES, or FALSE on error.

Every message in the current mailbox will be represented by three entries in the resulting array:

$thread["XX.num"] - current message number
$thread["XX.next"]
$thread["XX.branch"]

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

See also: imap_delete(), and imap_mail_move().

imap_unsubscribe

(PHP 3, PHP 4, PHP 5)

imap_unsubscribe -- Unsubscribe from a mailbox

Description

bool imap_unsubscribe ( string imap_stream, string mbox )

Unsubscribe from a specified mailbox.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

imap_utf7_decode

(PHP 3 >= 3.0.15, PHP 4, PHP 5)

imap_utf7_decode -- Decodes a modified UTF-7 encoded string

Description

string imap_utf7_decode ( string text )

Decodes modified UTF-7 text into ISO-8859-1 string.

Returns a string that is encoded in ISO-8859-1 and consists of the same sequence of characters in text, or FALSE if text contains invalid modified UTF-7 sequence or text contains a character that is not part of ISO-8859-1 character set.

This function is needed to decode mailbox names that contain certain characters which are not in range of printable ASCII characters.

The modified UTF-7 encoding is defined in RFC 2060, section 5.1.3 (original UTF-7 was defined in RFC1642).

imap_utf7_encode

(PHP 3 >= 3.0.15, PHP 4, PHP 5)

imap_utf7_encode -- Converts ISO-8859-1 string to modified UTF-7 text

Description

string imap_utf7_encode ( string data )

Converts data to modified UTF-7 text. Note that data is expected to be encoded in ISO-8859-1.

This is needed to encode mailbox names that contain certain characters which are not in range of printable ASCII characters.

The modified UTF-7 encoding is defined in RFC 2060, section 5.1.3 (original UTF-7 was defined in RFC1642).

imap_utf8

(PHP 3 >= 3.0.13, PHP 4, PHP 5)

imap_utf8 -- Converts MIME-encoded text to UTF-8

Description

string imap_utf8 ( string mime_encoded_text )

Converts the given mime_encoded_text to UTF-8. MIME encoding method and the UTF-8 specification are described in RFC2047 and RFC2044 respectively.

LVIII. Informix Functions

Introduzione

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 "php3_ifx.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.

Requisiti

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.

Installazione

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.

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

Nota: 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).

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").

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".

NULL values: The configuration variable ifx.nullformat (and the runtime function ifx_nullformat()) when set to TRUE will return NULL columns as the string "NULL", when set to FALSE they return the empty string. This allows you to discriminate between NULL columns and empty columns.

Tabella 1. Informix configuration options

Name	Default	Changeable
ifx.allow_persistent	"1"	PHP_INI_SYSTEM
ifx.max_persistent	"-1"	PHP_INI_SYSTEM
ifx.max_links	"-1"	PHP_INI_SYSTEM
ifx.default_host	NULL	PHP_INI_SYSTEM
ifx.default_user	NULL	PHP_INI_SYSTEM
ifx.default_password	NULL	PHP_INI_SYSTEM
ifx.blobinfile	"1"	PHP_INI_ALL
ifx.textasvarchar	"0"	PHP_INI_ALL
ifx.byteasvarchar	"0"	PHP_INI_ALL
ifx.charasvarchar	"0"	PHP_INI_ALL
ifx.nullformat	"0"	PHP_INI_ALL

Per maggiori dettagli sulle costanti PHP_INI_* vedere Appendice G.

Breve descrizione dei parametri di configurazione.

ifx.allow_persistent boolean: Whether to allow persistent Informix connections.
ifx.max_persistent integer: The maximum number of persistent Informix connections per process.
ifx.max_links integer: The maximum number of Informix connections per process, including persistent connections.
ifx.default_host string: The default host to connect to when no host is specified in ifx_connect() or ifx_pconnect(). Doesn't apply in modalità sicura.
ifx.default_user string: The default user id to use when none is specified in ifx_connect() or ifx_pconnect(). Doesn't apply in modalità sicura.
ifx.default_password string: The default password to use when none is specified in ifx_connect() or ifx_pconnect(). Doesn't apply in modalità sicura.
ifx.blobinfile boolean: Set to TRUE if you want to return blob columns in a file, FALSE if you want them in memory. You can override the setting at runtime with ifx_blobinfile_mode().
ifx.textasvarchar boolean: Set to TRUE if you want to return TEXT columns as normal strings in select statements, FALSE if you want to use blob id parameters. You can override the setting at runtime with ifx_textasvarchar().
ifx.byteasvarchar boolean: Set to TRUE if you want to return BYTE columns as normal strings in select queries, FALSE if you want to use blob id parameters. You can override the setting at runtime with ifx_textasvarchar().
ifx.charasvarchar boolean: Set to TRUE if you want to trim trailing spaces from CHAR columns when fetching them.
ifx.nullformat boolean: Set to TRUE if you want to return NULL columns as the literal string "NULL", FALSE if you want them returned as the empty string "". You can override this setting at runtime with ifx_nullformat().

Tipi di risorse

Costanti predefinite

Questa estensione non definisce alcuna costante.

Sommario
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 enumerated 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

ifx_affected_rows

(PHP 3 >= 3.0.3, PHP 4, PHP 5)

ifx_affected_rows -- Get number of rows affected by a query

Description

int ifx_affected_rows ( int result_id )

result_id is a valid result id returned by ifx_query() or ifx_prepare().

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).

int ifx_close ( [int link_identifier] )

Returns: always TRUE.

ifx_close() closes the link to an Informix database that's associated with the specified link identifier. If the link identifier isn't specified, the last opened link is assumed.

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().

Esempio 1. Closing a Informix connection
<?php $conn_id = ifx_connect ("mydb@ol_srv", "itsme", "mypassword"); /* ... some queries and stuff ... */ ifx_close($conn_id); ?>

ifx_connect

(PHP 3 >= 3.0.3, PHP 4, PHP 5)

ifx_connect -- Open Informix server connection

Description

int ifx_connect ( [string database [, string userid [, string password]]] )

Returns a connection identifier on success, or FALSE on error.

ifx_connect() establishes a connection to an Informix server. All of the arguments are optional, and if they're missing, defaults are taken from values supplied in configuration file (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).

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().

Esempio 1. Connect to a Informix database
<?php $conn_id = ifx_connect ("mydb@ol_srv1", "imyself", "mypassword"); ?>

See also ifx_pconnect() and ifx_close().

ifx_copy_blob

(PHP 3 >= 3.0.4, PHP 4, PHP 5)

ifx_copy_blob -- Duplicates the given blob object

Description

int ifx_copy_blob ( int bid )

Duplicates the given blob object. bid is the ID of the blob object.

Returns FALSE on error otherwise the new blob object-id.

ifx_create_blob

(PHP 3 >= 3.0.4, PHP 4, PHP 5)

ifx_create_blob -- Creates an blob object

Description

int ifx_create_blob ( int type, int mode, string param )

Creates an blob object.

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.

Return FALSE on error, otherwise the new blob object-id.

ifx_create_char

ifx_fetch_row

(PHP 3 >= 3.0.3, PHP 4, PHP 5)

ifx_fetch_row -- Get row as enumerated array

Description

array ifx_fetch_row ( int result_id [, mixed position] )

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. Returns FALSE on error

result_id is a valid resultid returned by ifx_query() or ifx_prepare() (select type queries only!).

position is 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.

ifx_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, with the column name as key.

Subsequent calls to ifx_fetch_row() would return the next row in the result set, or FALSE if there are no more rows.

Esempio 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 3 >= 3.0.3, PHP 4, PHP 5)

ifx_fieldproperties -- List of SQL fieldproperties

Description

array ifx_fieldproperties ( int result_id )

Returns an associative array with fieldnames as key and the SQL fieldproperties as data for a query with result_id. Returns FALSE on error.

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".

Esempio 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 3 >= 3.0.3, PHP 4, PHP 5)

ifx_fieldtypes -- List of Informix SQL fields

Description

Description

array ifx_getsqlca ( int result_id )

result_id is a valid result id returned by ifx_query() or ifx_prepare().

Returns a pseudo-row (associative array) 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.

Esempio 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 3 >= 3.0.3, PHP 4, PHP 5)

ifx_htmltbl_result -- Formats all rows of a query into a HTML table

Description

int ifx_htmltbl_result ( int result_id [, string html_table_options] )

Returns the number of rows fetched or FALSE on error.

Formats all rows of the result_id query into a HTML table. The optional second argument is a string of <table> tag options

Esempio 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 3 >= 3.0.4, PHP 4, PHP 5)

ifx_nullformat -- Sets the default return value on a fetch row

Description

void ifx_nullformat ( int mode )

Sets the default return value of a NULL-value on a fetch row. Mode "0" returns "", and mode "1" returns "NULL".

ifx_num_fields

(PHP 3 >= 3.0.3, PHP 4, PHP 5)

ifx_num_fields -- Returns the number of columns in the query

Description

int ifx_num_fields ( int result_id )

Returns the number of columns in query for result_id or FALSE on error

After preparing or executing a query, this call gives you the number of columns in the query.

ifx_num_rows

(PHP 3 >= 3.0.3, PHP 4, PHP 5)

ifx_num_rows -- Count the rows already fetched from a query

Description

int ifx_num_rows ( int result_id )

Gives the number of rows fetched so far for a query with result_id after a ifx_query() or ifx_do() query.

ifx_pconnect

(PHP 3 >= 3.0.3, PHP 4, PHP 5)

ifx_pconnect -- Open persistent Informix connection

Description

int ifx_pconnect ( [string database [, string userid [, string password]]] )

Returns: A positive Informix persistent link identifier on success, or FALSE on error

ifx_pconnect() acts very much like ifx_connect() with two major differences.

This function behaves exactly like ifx_connect() when PHP is not running as an Apache module. 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'.

ifx_prepare

(PHP 3 >= 3.0.4, PHP 4, PHP 5)

ifx_prepare -- Prepare an SQL-statement for execution

Description

int ifx_prepare ( string query, int conn_id [, int cursor_def, mixed blobidarray] )

Returns an integer result_id for use by ifx_do(). Sets affected_rows for retrieval by the ifx_affected_rows() function.

Introduzione

These functions allow you to access Ingres II database servers.

Nota: If you already used PHP extensions to access other database servers, note that Ingres doesn't allow concurrent queries and/or transaction over one connection, thus you won't find any result or transaction handle in this extension. The result of a query must be treated before sending another query, and a transaction must be committed or rolled back before opening another transaction (which is automatically done when sending the first query).

Requisiti

To compile PHP with Ingres support, you need the Open API library and header files included with Ingres II.

Installazione

In order to have these functions available, you must compile PHP with Ingres support by using the --with-ingres[=DIR] option, where DIR is the Ingres base directory, which defaults to /II/ingres. If the II_SYSTEM environment variable isn't correctly set you may have to use --with-ingres=DIR to specify your Ingres installation directory.

When using this extension with Apache, if Apache does not start and complains with "PHP Fatal error: Unable to start ingres_ii module in Unknown on line 0" then make sure the environment variable II_SYSTEM is correctly set. Adding "export II_SYSTEM="/home/ingres/II" in the script that starts Apache, just before launching httpd, should be fine.

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

Tabella 1. Ingres configuration options

Name	Default	Changeable	Changelog
ingres.allow_persistent	"1"	PHP_INI_SYSTEM	Available since PHP 4.0.2.
ingres.max_persistent	"-1"	PHP_INI_SYSTEM	Available since PHP 4.0.2.
ingres.max_links	"-1"	PHP_INI_SYSTEM	Available since PHP 4.0.2.
ingres.default_database	NULL	PHP_INI_ALL	Available since PHP 4.0.2.
ingres.default_user	NULL	PHP_INI_ALL	Available since PHP 4.0.2.
ingres.default_password	NULL	PHP_INI_ALL	Available since PHP 4.0.2.
ingres.report_db_warnings	"1"	PHP_INI_ALL	Available since version 1.1.0 of the PECL extension.
ingres.cursor_mode	"0"	PHP_INI_ALL	Available since version 1.1.0 of the PECL extension.
ingres.blob_segment_length	"4096"	PHP_INI_ALL	Available since version 1.2.0 of the PECL extension.

Per maggiori dettagli sulle costanti PHP_INI_* vedere Appendice G.

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

INGRES_ASSOC (integer): Columns are returned into the array having the fieldname as the array index.
INGRES_NUM (integer): Columns are returned into the array having a numerical index to the fields. This index starts with 1, the first field in the result.
INGRES_BOTH (integer): Columns are returned into the array having both a numerical index and the fieldname as the array index.
INGRES_EXT_VERSION (string): Specifies the version of the Ingres Extension. Available since version 1.2.0 of the PECL extension.
INGRES_API_VERSION (integer): Specifies the version of Ingres OpenAPI the extension was built against. Available since version 1.2.0 of the PECL extension.
INGRES_CURSOR_READONLY (integer): Specifies that Ingres cursors should be opened in 'readonly' mode. Available since version 1.2.0 of the PECL extension.
INGRES_CURSOR_UPDATE (integer): Specifies that Ingres cursors should be opened 'for update'. Available since version 1.2.0 of the PECL extension.
INGRES_DATE_MULTINATIONAL (integer): Equivalent to the II_DATE_FORMAT setting of MULTINATIONAL. Available since version 1.2.0 of the PECL extension.
INGRES_DATE_MULTINATIONAL4 (integer): Equivalent to the II_DATE_FORMAT setting of MULTINATIONAL4. Available since version 1.2.0 of the PECL extension.
INGRES_DATE_FINNISH (integer): Equivalent to the II_DATE_FORMAT setting of FINNISH. Available since version 1.2.0 of the PECL extension.
INGRES_DATE_ISO (integer): Equivalent to the II_DATE_FORMAT setting of ISO. Available since version 1.2.0 of the PECL extension.
INGRES_DATE_ISO4 (integer): Equivalent to the II_DATE_FORMAT setting of ISO4. Available since version 1.2.0 of the PECL extension.
INGRES_DATE_GERMAN (integer): Equivalent to the II_DATE_FORMAT setting of GERMAN. Available since version 1.2.0 of the PECL extension.
INGRES_DATE_MDY (integer): Equivalent to the II_DATE_FORMAT setting of MDY. Available since version 1.2.0 of the PECL extension.
INGRES_DATE_DMY (integer): Equivalent to the II_DATE_FORMAT setting of DMY. Available since version 1.2.0 of the PECL extension.
INGRES_DATE_YMD (integer): Equivalent to the II_DATE_FORMAT setting of YMD. Available since version 1.2.0 of the PECL extension.
INGRES_MONEY_LEADING (integer): Speifies the currency character should be placed a the start of a money value. Equivalent to setting II_MONEY_FORMAT to 'L:'. Available since version 1.2.0 of the PECL extension.
INGRES_MONEY_TRAILING (integer): Speifies the currency character should be placed a the end of a money value. Equivalent to setting II_MONEY_FORMAT to 'T:'. Available since version 1.2.0 of the PECL extension.

Sommario
ingres_autocommit -- Switch autocommit on or off
ingres_close -- Close an Ingres II database connection
ingres_commit -- Commit a transaction
ingres_connect -- Open a connection to an Ingres II database
ingres_cursor -- Gets a cursor name for a given link resource
ingres_errno -- Gets the last ingres error number generated
ingres_error -- Gets a meaningful error message for the last error generated
ingres_errsqlstate -- Gets the last SQLSTATE error code generated
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_field_length -- Get the length of a field
ingres_field_name -- Get the name of a field in a query result
ingres_field_nullable -- Test if a field is nullable
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_num_fields -- Get the number of fields returned by the last query
ingres_num_rows -- Get the number of rows affected or returned by the last query
ingres_pconnect -- Open a persistent connection to an Ingres II database
ingres_query -- Send a SQL query to Ingres II
ingres_rollback -- Roll back a transaction

ingres_autocommit

(PHP 4 >= 4.0.2, PHP 5 <= 5.0.4)

ingres_autocommit -- Switch autocommit on or off

resource ingres_connect ( [string database [, string username [, string password]]] )

Returns a Ingres II link resource on success, or FALSE on failure.

string ingres_errsqlstate ( [resource link] )

Returns a string containing the last SQLSTATE, or NULL if no error has occurred.

If a link resource is passed to ingres_errsqlstate() it returns the last error recorded for the link. If no link is passed then ingres_errsqlstate() returns the last error reported using the default link.

The function, ingres_errsqlstate(), should always be called after executing any database query. Calling another function before ingres_errsqlstate() is called will reset or change any error message from the last Ingres function call.

Esempio 1. ingres_errsqlstate() example
<?php ingres_connect($database, $user, $password); ingres_query("select * from table"); $error_sqlstate = ingres_errsqlstate(); if ( is_null($error_sqlstate) ) { echo "An error occured - " . $error_sqlstate; } ?>

See also ingres_errno() and ingres_errsqlstate().

ingres_fetch_array

(PHP 4 >= 4.0.2, PHP 5 <= 5.0.4)

ingres_fetch_array -- Fetch a row of result into an array

Description

array ingres_fetch_array ( [int result_type [, resource link]] )

ingres_fetch_array() Returns an array that corresponds to the fetched row, or FALSE if there are no more rows.

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 other column(s) of the same name, you must use the numeric index of the column or make an alias for the column.

<?php

ingres_query("select t1.f1 as foo t2.f1 as bar from t1, t2");
$result = ingres_fetch_array();
$foo = $result["foo"];
$bar = $result["bar"];

?>

result_type can be INGRES_NUM for enumerated array, INGRES_ASSOC for associative array, or INGRES_BOTH (default).

Speed-wise, the function is identical to ingres_fetch_object(), and almost as quick as ingres_fetch_row() (the difference is insignificant).

Esempio 1. ingres_fetch_array() example
<?php ingres_connect($database, $user, $password); ingres_query("select * from table"); while ($row = ingres_fetch_array()) { echo $row["user_id"]; // using associative array echo $row["fullname"]; echo $row[1]; // using enumerated array echo $row[2]; } ?>

ingres_fetch_object

(PHP 4 >= 4.0.2, PHP 5 <= 5.0.4)

ingres_fetch_object -- Fetch a row of result into an object

Description

object ingres_fetch_object ( [int result_type [, resource link]] )

ingres_fetch_object() Returns an object that corresponds to the fetched row, or FALSE if there are no more rows.

This function is similar to ingres_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).

The optional argument result_type is a constant and can take the following values: INGRES_ASSOC, INGRES_NUM, and INGRES_BOTH.

Speed-wise, the function is identical to ingres_fetch_array(), and almost as quick as ingres_fetch_row() (the difference is insignificant).

Esempio 1. ingres_fetch_object() example
<?php ingres_connect($database, $user, $password); ingres_query("select * from table"); while ($row = ingres_fetch_object()) { echo $row->user_id; echo $row->fullname; } ?>

ingres_fetch_row

(PHP 4 >= 4.0.2, PHP 5 <= 5.0.4)

ingres_fetch_row -- Fetch a row of result into an enumerated array

Description

array ingres_fetch_row ( [resource link] )

Returns TRUE on success, or FALSE on failure.

ingres_query() sends the given query to the Ingres server. This query must be a valid SQL query (see the Ingres SQL reference guide)

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 either call 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.

Some types of SQL queries can't 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

Esempio 1. ingres_query() example
<?php ingres_connect($database, $user, $password); ingres_query("select * from table"); while ($row = ingres_fetch_row()) { echo $row[1]; echo $row[2]; } ?>

ingres_rollback

(PHP 4 >= 4.0.2, PHP 5 <= 5.0.4)

ingres_rollback -- Roll back a transaction

Description

bool ingres_rollback ( [resource link] )

ingres_rollback() rolls back the currently open transaction, actually canceling all changes made to the database during the transaction.

This closes the transaction. A new one can be open by sending a query with ingres_query().

LX. IRC Gateway Functions

Introduzione

With IRCG you can rapidly stream XML data to thousands of concurrently connected users. This can be used to build powerful, extensible interactive platforms such as online games and webchats. IRCG also features support for a non-streaming mode where a helper application reformats incoming data and supplies static file snippets in special formats such as cHTML (i-mode) or WML (WAP). These static files are then delivered by the high-performance web server.

Up to v4, IRCG runs under these platforms:

AIX
FreeBSD
HP-UX
Irix
Linux
Solaris
Tru64
Windows

Nota: Questo modulo è stato spostato nel repository PECL e non sarà più rilascio con il PHP dalla versione 5.1.0.

Installazione

Detailed installation instructions can be found at http://www.schumann.cx/ircg/. We urge you to use the provided installation script.

It is not recommended, but you can try enable IRCG support yourself. Provide the path to the ircg-config script, --with-ircg-config=path/to/irc-config and in addition add --with-ircg to your configure line.

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Tipi di risorse

Costanti predefinite

Questa estensione non definisce alcuna costante.

Sommario
ircg_channel_mode -- Set channel mode flags for user
ircg_disconnect -- Close connection to server
ircg_eval_ecmascript_params -- Decodes a list of JS-encoded parameters
ircg_fetch_error_msg -- Returns the error from previous IRCG operation
ircg_get_username -- Get username for connection
ircg_html_encode -- Encodes HTML preserving output
ircg_ignore_add -- Add a user to your ignore list on a server
ircg_ignore_del -- Remove a user from your ignore list on a server
ircg_invite -- Invites nickname to channel
ircg_is_conn_alive -- Check connection status
ircg_join -- Join a channel on a connected server
ircg_kick -- Kick a user out of a channel on server
ircg_list -- List topic/user count of channel(s)
ircg_lookup_format_messages -- Check for the existence of a format message set
ircg_lusers -- IRC network statistics
ircg_msg -- Send message to channel or user on server
ircg_names -- Query visible usernames
ircg_nick -- Change nickname on server
ircg_nickname_escape -- Encode special characters in nickname to be IRC-compliant
ircg_nickname_unescape -- Decodes encoded nickname
ircg_notice -- Send a notice to a user on server
ircg_oper -- Elevates privileges to IRC OPER
ircg_part -- Leave a channel on server
ircg_pconnect -- Connect to an IRC server
ircg_register_format_messages -- Register a format message set
ircg_set_current -- Set current connection for output
ircg_set_file -- Set logfile for connection
ircg_set_on_die -- Set action to be executed when connection dies
ircg_topic -- Set topic for channel on server
ircg_who -- Queries server for WHO information
ircg_whois -- Query server for user information

ircg_channel_mode

(PHP 4 >= 4.0.5, PHP 5 <= 5.0.4)

ircg_channel_mode -- Set channel mode flags for user

Description

bool ircg_channel_mode ( resource connection, string channel, string mode_spec, string nick )

Set channel mode flags for channel on server connected to by connection. Mode flags are passed in mode_spec and are applied to the user specified by nick.

Mode flags are set or cleared by specifying a mode character and prepending it with a plus or minus character, respectively. E.g. operator mode is granted by '+o' and revoked by '-o', as passed as mode_spec.

ircg_disconnect

(PHP 4 >= 4.0.4, PHP 5 <= 5.0.4)

ircg_disconnect -- Close connection to server

Description

resource ircg_pconnect ( string username [, string server_ip [, int server_port [, string msg_format [, array ctcp_messages [, array user_settings [, bool bailout_on_trivial]]]]]] )

ircg_pconnect() will try to establish a connection to an IRC server and return a connection resource handle for further use.

The only mandatory parameter is username, this will set your initial nickname on the server. server_ip and server_port are optional and default to 127.0.0.1 and 6667.

Nota: For now parameter server_ip will not do any hostname lookups and will only accept IP addresses in numerical form. DNS lookups are expensive and should be done in the context of IRCG.

You can customize the output of IRC messages and events by selecting a format message set previously created with ircg_register_format_messages() by specifying the set's name in msg_format.

If you want to handle CTCP messages such as ACTION (/me), you need to define a mapping from CTCP type (e.g. ACTION) to a custom format string. Do this by passing an associative array as ctcp_messages. The keys of the array are the CTCP type and the respective value is the format message.

You can define "ident", "password", and "realname" tokens which are sent to the IRC server by setting these in an associative array. Pass that array as user_settings.

ircg_register_format_messages

(PHP 4 >= 4.0.5, PHP 5 <= 5.0.4)

ircg_register_format_messages -- Register a format message set

Description

bool ircg_register_format_messages ( string name, array messages )

With ircg_register_format_messages() you can customize the way your IRC output looks like or which script functions are invoked on the client side.

Plain channel message
Private message received
Private message sent
Some user leaves channel
Some user enters channel
Some user was kicked from the channel
Topic has been changed
Error
Fatal error
Join list end(?)
Self part(?)
Some user changes his nick
Some user quits his connection
Mass join begin
Mass join element
Mass join end
Whois user
Whois server
Whois idle
Whois channel
Whois end
Voice status change on user
Operator status change on user
Banlist
Banlist end

%f - from
%t - to
%c - channel
%r - plain message
%m - encoded message
%j - js encoded message

1 - mod encode
2 - nickname decode

This feature requires IRCG 3.

ircg_topic

(PHP 4 >= 4.0.5, PHP 5 <= 5.0.4)

ircg_topic -- Set topic for channel on server

Description

bool ircg_topic ( resource connection, string channel, string new_topic )

Change the topic for channel channel on the server connected to by connection to new_topic.

ircg_who

(PHP 4 >= 4.3.3, PHP 5 <= 5.0.4)

ircg_who -- Queries server for WHO information

Description

bool ircg_who ( resource connection, string mask [, bool ops_only] )

ircg_who() will request a list of users whose nickname is matching mask on connected network connection. The optional parameter ops_only will shrink the list to server operators only.

The answer is sent to the output defined by ircg_set_file() or ircg_set_current(). Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

ircg_whois

(PHP 4 >= 4.0.5, PHP 5 <= 5.0.4)

ircg_whois -- Query server for user information

Description

bool ircg_whois ( resource connection, string nick )

Sends a query to the connected server connection to ask for information about the specified user nick.

LXI. PHP / Java Integration

Introduzione

There are two possible ways to bridge PHP and Java: you can either integrate PHP into a Java Servlet environment, which is the more stable and efficient solution, or integrate Java support into PHP. The former is provided by a SAPI module that interfaces with the Servlet server, the latter by this Java extension.

The Java extension provides a simple and effective means for creating and invoking methods on Java objects from PHP. The JVM is created using JNI, and everything runs in-process.

Avvertimento

Requisiti

You need a Java VM installed on your machine to use this extension.

Installazione

This PECL extension is not bundled with PHP.

In PHP 4 this PECL extensions source can be found in the ext/ directory within the PHP source or at the PECL link above. In order to use these functions you must compile PHP with Java support by using the --with-java[=DIR] where DIR points to the base install directory of your JDK. This extension can only be built as a shared extension. Additional build extensions can be found in php-src/ext/java/README.

Windows users will enable php_java.dll inside of php.ini in order to use these functions. In PHP 4 this DLL resides in the extensions/ directory within the PHP Windows binaries download. You may download this PECL extension DLL from the PHP Downloads page or at http://snaps.php.net/.

Nota: In order to enable this module on a Windows environment with PHP <= 4.0.6, you must make jvm.dll available to your systems PATH. No additional DLL is needed for PHP versions > 4.0.6.

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

Tabella 1. Java configuration options

Name	Default	Changeable
java.class.path	NULL	PHP_INI_ALL
java.home	NULL	PHP_INI_ALL
java.library.path	NULL	PHP_INI_ALL
java.library	JAVALIB	PHP_INI_ALL

Per maggiori dettagli sulle costanti PHP_INI_* vedere Appendice G.

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

Questa estensione non definisce alcuna costante.

Esempi

Esempio 1. Java Example
<?php // get instance of Java class java.lang.System in PHP $system = new Java('java.lang.System'); // demonstrate property access echo 'Java version=' . $system->getProperty('java.version') . '<br />'; echo 'Java vendor=' . $system->getProperty('java.vendor') . '<br />'; echo 'OS=' . $system->getProperty('os.name') . ' ' . $system->getProperty('os.version') . ' on ' . $system->getProperty('os.arch') . ' <br />'; // java.util.Date example $formatter = new Java('java.text.SimpleDateFormat', "EEEE, MMMM dd, yyyy 'at' h:mm:ss a zzzz"); echo $formatter->format(new Java('java.util.Date')); ?>

Esempio 2. AWT Example
<?php // This example is only intended to be run as a CGI. $frame = new Java('java.awt.Frame', 'PHP'); $button = new Java('java.awt.Button', 'Hello Java World!'); $frame->add('North', $button); $frame->validate(); $frame->pack(); $frame->visible = True; $thread = new Java('java.lang.Thread'); $thread->sleep(10000); $frame->dispose(); ?>
Notes:

new Java() will create an instance of a class if a suitable constructor is available. If no parameters are passed and the default constructor is useful as it provides access to classes like java.lang.System which expose most of their functionallity through static methods.
Accessing a member of an instance will first look for bean properties then public fields. In other words, print $date.time will first attempt to be resolved as $date.getTime(), then as $date.time.
Both static and instance members can be accessed on an object with the same syntax. Furthermore, if the java object is of type java.lang.Class, then static members of the class (fields and methods) can be accessed.
Exceptions raised result in PHP warnings, and NULL results. The warnings may be eliminated by prefixing the method call with an "@" sign. The following APIs may be used to retrieve and reset the last error:
- java_last_exception_get()
- java_last_exception_clear()
Overload resolution is in general a hard problem given the differences in types between the two languages. The PHP Java extension employs a simple, but fairly effective, metric for determining which overload is the best match.
Additionally, method names in PHP are not case sensitive, potentially increasing the number of overloads to select from.
Once a method is selected, the parameters are coerced if necessary, possibly with a loss of data (example: double precision floating point numbers will be converted to boolean).
In the tradition of PHP, arrays and hashtables may pretty much be used interchangably. Note that hashtables in PHP may only be indexed by integers or strings; and that arrays of primitive types in Java can not be sparse. Also note that these constructs are passed by value, so may be expensive in terms of memory and time.

Java Servlet SAPI

The Java Servlet SAPI builds upon the mechanism defined by the Java extension to enable the entire PHP processor to be run as a servlet. The primary advantage of this from a PHP perspective is that web servers which support servlets typically take great care in pooling and reusing JVMs. Build instructions for the Servlet SAPI module can be found in php4/sapi/README. Notes:

While this code is intended to be able to run on any servlet engine, it has only been tested on Apache's Jakarta/tomcat to date. Bug reports, success stories and/or patches required to get this code to run on other engines would be appreciated.
PHP has a habit of changing the working directory. sapi/servlet will eventually change it back, but while PHP is running the servlet engine may not be able to load any classes from the CLASSPATH which are specified using a relative directory syntax, or find the work directory used for administration and JSP compilation tasks.

Sommario
java_last_exception_clear -- Clear last Java exception
java_last_exception_get -- Get last Java exception

java_last_exception_clear

(PHP 4 >= 4.0.2, PECL)

java_last_exception_clear -- Clear last Java exception

Description

void java_last_exception_clear ( void )

Avvertimento

See java_last_exception_get() for an example.

java_last_exception_get

(PHP 4 >= 4.0.2, PECL)

java_last_exception_get -- Get last Java exception

Description

object java_last_exception_get ( void )

Avvertimento

The following example demonstrates the usage of Java's exception handler from within PHP:
Esempio 1. Java exception handler
<?php $stack = new Java('java.util.Stack'); $stack->push(1); // This should succeed $result = $stack->pop(); $ex = java_last_exception_get(); if (!$ex) { echo "$result\n"; } // This should fail (error suppressed by @) $result = @$stack->pop(); $ex = java_last_exception_get(); if ($ex) { echo $ex->toString(); } // Clear last exception java_last_exception_clear(); ?>

LXII. KADM5

Introduzione

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.

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

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:

Tabella 1. Attributes for use by the KDC

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:

Tabella 2. Options for creating/modifying/retrieving principals

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.

Esempi

This simple example shows how to connect, query, print resulting principals and disconnect from a KADM5 database.
Esempio 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); ?>

Contact Information

If you have comments, bugfixes, enhancements or want to help in developing this you can send me a mail at holger.burbach@gonicus.de. The project homepage can be found at http://oss.gonicus.de/project/?group_id=7.

Sommario
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, leaving the connection to the Kerberos admin server open
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 and initializes any neccessary state information
kadm5_modify_principal -- Modifies a kerberos principal with the given parameters

kadm5_chpass_principal

(PECL)

kadm5_chpass_principal -- Changes the principal's password

Descrizione

bool kadm5_chpass_principal ( resource handle, string principal, string password )

kadm5_chpass_principal() sets the new password password for the principal.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 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_create_principal -- Creates a kerberos principal with the given parameters

Descrizione

bool kadm5_create_principal ( resource handle, string principal [, string password [, array options]] )

kadm5_create_principal() creates a principal with the given password. If password is omitted or is NULL, a random key will be generated.

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.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 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); ?>

kadm5_delete_principal

(PECL)

kadm5_delete_principal -- Deletes a kerberos principal

Descrizione

bool kadm5_delete_principal ( resource handle, string principal )

kadm5_delete_principal() remove the principal from the Kerberos database.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 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); ?>

kadm5_destroy

(PECL)

kadm5_destroy -- Closes the connection to the admin server and releases all related resources

Descrizione

bool kadm5_destroy ( resource handle )

Nota: Connection should be closed after use with kadm5_destroy().

Vedere anche:

kadm5_destroy()

kadm5_modify_principal

(PECL)

kadm5_modify_principal -- Modifies a kerberos principal with the given parameters

Descrizione

bool kadm5_modify_principal ( resource handle, string principal, array options )

kadm5_modify_principal() modifies a principal according to the given 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.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 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", "password", $options); kadm5_destroy($handle); ?>

LXIII. LDAP Functions

Introduzione

LDAP is the Lightweight Directory Access Protocol, and is a protocol used to access "Directory Servers". The Directory is a special kind of database that holds information in a tree structure.

The concept is similar to your hard disk directory structure, except that in this context, the root directory is "The world" and the first level subdirectories are "countries". Lower levels of the directory structure contain entries for companies, organisations or places, while yet lower still we find directory entries for people, and perhaps equipment or documents.

To refer to a file in a subdirectory on your hard disk, you might use something like:

/usr/local/myapp/docs

The forwards slash marks each division in the reference, and the sequence is read from left to right.

The equivalent to the fully qualified file reference in LDAP is the "distinguished name", referred to simply as "dn". An example dn might be:

cn=John Smith,ou=Accounts,o=My Company,c=US

The comma marks each division in the reference, and the sequence is read from right to left. You would read this dn as:

     country = US
     organization = My Company
     organizationalUnit = Accounts
     commonName = John Smith

In the same way as there are no hard rules about how you organise the directory structure of a hard disk, a directory server manager can set up any structure that is meaningful for the purpose. However, there are some conventions that are used. The message is that you can not write code to access a directory server unless you know something about its structure, any more than you can use a database without some knowledge of what is available.

Lots of information about LDAP can be found at

The Netscape SDK contains a helpful Programmer's Guide in HTML format.

Requisiti

You will need to get and compile LDAP client libraries from either OpenLDAP or Bind9.net in order to compile PHP with LDAP support.

Installazione

LDAP support in PHP is not enabled by default. You will need to use the --with-ldap[=DIR] configuration option when compiling PHP to enable LDAP support. DIR is the LDAP base install directory. To enable SASL support, be sure --with-ldap-sasl[=DIR] is used, and that sasl.h exists on the system.

Note to Win32 Users: In order to enable this module on a Windows environment, you must copy several files from the DLL folder of the PHP/Win32 binary package to the SYSTEM folder of your windows machine. (Ex: C:\WINNT\SYSTEM32, or C:\WINDOWS\SYSTEM). For PHP <= 4.2.0 copy libsasl.dll, for PHP >= 4.3.0 copy libeay32.dll and ssleay32.dll to your SYSTEM folder.

In order to use Oracle LDAP libraries, proper Oracle environment has to be set.

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

Tabella 1. LDAP configuration options

Name	Default	Changeable	Changelog
ldap.max_links	"-1"	PHP_INI_SYSTEM

Per maggiori dettagli sulle costanti PHP_INI_* vedere Appendice G.

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

LDAP_DEREF_NEVER (integer)
LDAP_DEREF_SEARCHING (integer)
LDAP_DEREF_FINDING (integer)
LDAP_DEREF_ALWAYS (integer)
LDAP_OPT_DEREF (integer)
LDAP_OPT_SIZELIMIT (integer)
LDAP_OPT_TIMELIMIT (integer)
LDAP_OPT_PROTOCOL_VERSION (integer)
LDAP_OPT_ERROR_NUMBER (integer)
LDAP_OPT_REFERRALS (integer)
LDAP_OPT_RESTART (integer)
LDAP_OPT_HOST_NAME (integer)
LDAP_OPT_ERROR_STRING (integer)
LDAP_OPT_MATCHED_DN (integer)
LDAP_OPT_SERVER_CONTROLS (integer)
LDAP_OPT_CLIENT_CONTROLS (integer)
LDAP_OPT_DEBUG_LEVEL (integer)
GSLC_SSL_NO_AUTH (integer)
GSLC_SSL_ONEWAY_AUTH (integer)
GSLC_SSL_TWOWAY_AUTH (integer)

Esempi

Retrieve information for all entries where the surname starts with "S" from a directory server, displaying an extract with name and email address.

Esempio 1. LDAP search example

<?php
// basic sequence with LDAP is connect, bind, search, interpret search
// result, close connection

echo "<h3>LDAP query test</h3>";
echo "Connecting ...";
$ds=ldap_connect("localhost");  // must be a valid LDAP server!
echo "connect result is " . $ds . "<br />";

if ($ds) { 
    echo "Binding ..."; 
    $r=ldap_bind($ds);     // this is an "anonymous" bind, typically
                           // read-only access
    echo "Bind result is " . $r . "<br />";

    echo "Searching for (sn=S*) ...";
    // Search surname entry
    $sr=ldap_search($ds, "o=My Company, c=US", "sn=S*");  
    echo "Search result is " . $sr . "<br />";

    echo "Number of entires returned is " . ldap_count_entries($ds, $sr) . "<br />";

    echo "Getting entries ...<p>";
    $info = ldap_get_entries($ds, $sr);
    echo "Data for " . $info["count"] . " items returned:<p>";

    for ($i=0; $i<$info["count"]; $i++) {
        echo "dn is: " . $info[$i]["dn"] . "<br />";
        echo "first cn entry is: " . $info[$i]["cn"][0] . "<br />";
        echo "first email entry is: " . $info[$i]["mail"][0] . "<br /><hr />";
    }

    echo "Closing connection";
    ldap_close($ds);

} else {
    echo "<h4>Unable to connect to LDAP server</h4>";
}
?>

Using the PHP LDAP calls

Before you can use the LDAP calls you will need to know ..

The name or address of the directory server you will use
The "base dn" of the server (the part of the world directory that is held on this server, which could be "o=My Company,c=US")
Whether you need a password to access the server (many servers will provide read access for an "anonymous bind" but require a password for anything else)

The typical sequence of LDAP calls you will make in an application will follow this pattern:

  ldap_connect()    // establish connection to server
     |
  ldap_bind()       // anonymous or authenticated "login"
     |
  do something like search or update the directory
  and display the results
     |
  ldap_close()      // "logout"

Sommario
ldap_8859_to_t61 -- Translate 8859 characters to t61 characters
ldap_add -- Add entries to LDAP directory
ldap_bind -- Bind to LDAP directory
ldap_close -- Alias di ldap_unbind()
ldap_compare -- Compare value of attribute found in entry specified with DN
ldap_connect -- Connect to an LDAP server
ldap_count_entries -- Count the number of entries in a search
ldap_delete -- Delete an entry from a directory
ldap_dn2ufn -- Convert DN to User Friendly Naming format
ldap_err2str -- Convert LDAP error number into string error message
ldap_errno -- Return the LDAP error number of the last LDAP command
ldap_error -- Return the LDAP error message of the last LDAP command
ldap_explode_dn -- Splits DN into its component parts
ldap_first_attribute -- Return first attribute
ldap_first_entry -- Return first result id
ldap_first_reference -- Return first reference
ldap_free_result -- Free result memory
ldap_get_attributes -- Get attributes from a search result entry
ldap_get_dn -- Get the DN of a result entry
ldap_get_entries -- Get all result entries
ldap_get_option -- Get the current value for given option
ldap_get_values_len -- Get all binary values from a result entry
ldap_get_values -- Get all values from a result entry
ldap_list -- Single-level search
ldap_mod_add -- Add attribute values to current attributes
ldap_mod_del -- Delete attribute values from current attributes
ldap_mod_replace -- Replace attribute values with new ones
ldap_modify -- Modify an LDAP entry
ldap_next_attribute -- Get the next attribute in result
ldap_next_entry -- Get next result entry
ldap_next_reference -- Get next reference
ldap_parse_reference -- Extract information from reference entry
ldap_parse_result -- Extract information from result
ldap_read -- Read an entry
ldap_rename -- Modify the name of an entry
ldap_sasl_bind -- Bind to LDAP directory using SASL
ldap_search -- Search LDAP tree
ldap_set_option -- Set the value of the given option
ldap_set_rebind_proc -- Set a callback function to do re-binds on referral chasing
ldap_sort -- Sort LDAP result entries
ldap_start_tls -- Start TLS
ldap_t61_to_8859 -- Translate t61 characters to 8859 characters
ldap_unbind -- Unbind from LDAP directory

ldap_8859_to_t61

(PHP 4 >= 4.0.2, PHP 5)

ldap_8859_to_t61 -- Translate 8859 characters to t61 characters

Description

string ldap_8859_to_t61 ( string value )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

ldap_add

(PHP 3, PHP 4, PHP 5)

ldap_add -- Add entries to LDAP directory

Description

bool ldap_add ( resource link_identifier, string dn, array entry )

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

The ldap_add() function is used to add entries in the LDAP directory. The DN of the entry to be added is specified by dn. Array entry specifies the information about the entry. The values in the entries are indexed by individual attributes. In case of multiple values for an attribute, they are indexed using integers starting with 0.

<?php
$entree["attribut1"] = "value";
$entree["attribut2"][0] = "value1";
$entree["attribut2"][1] = "value2";
?>

Esempio 1. Complete example with authenticated bind

<?php
$ds=ldap_connect("localhost");  // assuming the LDAP server is on this host

if ($ds) {
    // bind with appropriate dn to give update access
    $r=ldap_bind($ds, "cn=root, o=My Company, c=US", "secret");

    // prepare data
    $info["cn"]="John Jones";
    $info["sn"]="Jones";
    $info["mail"]="jonj@example.com";
    $info["objectclass"]="person";

    // add data to directory
    $r=ldap_add($ds, "cn=John Jones, o=My Company, c=US", $info);

    ldap_close($ds);
} else {
    echo "Unable to connect to LDAP server"; 
}
?>

Nota: Questa funzione è binary-safe (gestisce correttamente i file binari)

ldap_bind

(PHP 3, PHP 4, PHP 5)

ldap_bind -- Bind to LDAP directory

Description

bool ldap_bind ( resource link_identifier [, string bind_rdn [, string bind_password]] )

Binds to the LDAP directory with specified RDN and password. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

ldap_bind() does a bind operation on the directory. bind_rdn and bind_password are optional. If not specified, anonymous bind is attempted.

Esempio 1. Using LDAP Bind

<?php

// using ldap bind
$ldaprdn  = 'uname';     // ldap rdn or dn
$ldappass = 'password';  // associated password

// connect to ldap server
$ldapconn = ldap_connect("ldap.example.com")
    or die("Could not connect to LDAP server.");

if ($ldapconn) {

    // binding to ldap server
    $ldapbind = ldap_bind($ldapconn, $ldaprdn, $ldappass);

    // verify binding
    if ($ldapbind) {
        echo "LDAP bind successful...";
    } else {
        echo "LDAP bind failed...";
    }
        
}

?>

Esempio 2. Using LDAP Bind Anonymously

<?php

//using ldap bind anonymously

// connect to ldap server
$ldapconn = ldap_connect("ldap.example.com")
    or die("Could not connect to LDAP server.");

if ($ldapconn) {

    // binding anonymously
    $ldapbind = ldap_bind($ldapconn);

    if ($ldapbind) {
        echo "LDAP bind anonymous successful...";
    } else {
        echo "LDAP bind anonymous failed...";
    }
 
}
    
?>

ldap_close

(PHP 3, PHP 4, PHP 5)

ldap_close -- Alias di ldap_unbind()

Descrizione

This function is an alias of: ldap_unbind().

ldap_compare

(PHP 4 >= 4.0.2, PHP 5)

ldap_compare -- Compare value of attribute found in entry specified with DN

Description

mixed ldap_compare ( resource link_identifier, string dn, string attribute, string value )

Returns TRUE if value matches otherwise returns FALSE. Returns -1 on error.

ldap_compare() is used to compare value of attribute to value of same attribute in LDAP directory entry specified with dn.

The following example demonstrates how to check whether or not given password matches the one defined in DN specified entry.

Esempio 1. Complete example of password check

<?php

$ds=ldap_connect("localhost");  // assuming the LDAP server is on this host
      
if ($ds) {

    // bind 
    if (ldap_bind($ds)) {

        // prepare data
        $dn = "cn=Matti Meikku, ou=My Unit, o=My Company, c=FI";
        $value = "secretpassword";
        $attr = "password"; 

        // compare value
        $r=ldap_compare($ds, $dn, $attr, $value);

        if ($r === -1) {
            echo "Error: " . ldap_error($ds);
        } elseif ($r === true) {
            echo "Password correct.";
        } elseif ($r === false) {
            echo "Wrong guess! Password incorrect.";
        }

    } else {
        echo "Unable to bind to LDAP server.";
    }          

    ldap_close($ds);

} else {
    echo "Unable to connect to LDAP server.";
}
?>

Avvertimento

ldap_compare() can NOT be used to compare BINARY values!

Nota: This function was added in 4.0.2.

ldap_connect

(PHP 3, PHP 4, PHP 5)

ldap_connect -- Connect to an LDAP server

Description

resource ldap_connect ( [string hostname [, int port]] )

Returns a positive LDAP link identifier on success, or FALSE on error. When OpenLDAP 2.x.x is used, ldap_connect() will always return a resource as it does not actually connect but just initializes the connecting parameters. The actual connect happens with the next calls to ldap_* funcs, usually with ldap_bind().

ldap_connect() establishes a connection to a LDAP server on a specified hostname and port. Both the arguments are optional. If no arguments are specified then the link identifier of the already opened link will be returned. If only hostname is specified, then the port defaults to 389.

If you are using OpenLDAP 2.x.x you can specify a URL instead of the hostname. To use LDAP with SSL, compile OpenLDAP 2.x.x with SSL support, configure PHP with SSL, and use ldaps://hostname/ as host parameter. The port parameter is not used when using URLs.

Nota: URL and SSL support were added in 4.0.4.

Esempio 1. Example of connecting to LDAP server.

<?php

// LDAP variables
$ldaphost = "ldap.example.com";  // your ldap servers
$ldapport = 389;                 // your ldap server's port number

// Connecting to LDAP
$ldapconn = ldap_connect($ldaphost, $ldapport) 
          or die("Could not connect to $ldaphost");

?>

Esempio 2. Example of connecting securely to LDAP server.

<?php

// make sure your host is the correct one
// that you issued your secure certificate to
$ldaphost = "ldaps://ldap.example.com/";

// Connecting to LDAP
$ldapconn = ldap_connect($ldaphost) 
          or die("Could not connect to {$ldaphost}");

?>

(PHP 3 >= 3.0.13, PHP 4, PHP 5)

ldap_err2str -- Convert LDAP error number into string error message

bool ldap_free_result ( resource result_identifier )

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

ldap_free_result() frees up the memory allocated internally to store the result and pointed by the result_identifier. All result memory will be automatically freed when the script terminates.

Typically all the memory allocated for the ldap result gets freed at the end of the script. In case the script is making successive searches which return large result sets, ldap_free_result() could be called to keep the runtime memory usage by the script low.

ldap_get_attributes

(PHP 3, PHP 4, PHP 5)

ldap_get_attributes -- Get attributes from a search result entry

Description

array ldap_get_attributes ( resource link_identifier, resource result_entry_identifier )

Returns a complete entry information in a multi-dimensional array on success and FALSE on error.

ldap_get_attributes() function is used to simplify reading the attributes and values from an entry in the search result. The return value is a multi-dimensional array of attributes and values.

Having located a specific entry in the directory, you can find out what information is held for that entry by using this call. You would use this call for an application which "browses" directory entries and/or where you do not know the structure of the directory entries. In many applications you will be searching for a specific attribute such as an email address or a surname, and won't care what other data is held.

return_value["count"] = number of attributes in the entry
return_value[0] = first attribute
return_value[n] = nth attribute

return_value["attribute"]["count"] = number of values for attribute
return_value["attribute"][0] = first value of the attribute
return_value["attribute"][i] = (i+1)th value of the attribute

Esempio 1. Show the list of attributes held for a particular directory entry

<?php
// $ds is the link identifier for the directory

// $sr is a valid search result from a prior call to
// one of the ldap directory search calls

$entry = ldap_first_entry($ds, $sr);

$attrs = ldap_get_attributes($ds, $entry);

echo $attrs["count"] . " attributes held for this entry:<p>";

for ($i=0; $i<$attrs["count"]; $i++) {
    echo $attrs[$i] . "<br />";
}
?>

ldap_get_dn

(PHP 3, PHP 4, PHP 5)

ldap_get_dn -- Get the DN of a result entry

Description

ldap_get_values() function is used to read all the values of the attribute in the entry in the result. entry is specified by the result_entry_identifier. The number of values can be found by indexing "count" in the resultant array. Individual values are accessed by integer index in the array. The first index is 0.

This call needs a result_entry_identifier, so needs to be preceded by one of the ldap search calls and one of the calls to get an individual entry.

You application will either be hard coded to look for certain attributes (such as "surname" or "mail") or you will have to use the ldap_get_attributes() call to work out what attributes exist for a given entry.

LDAP allows more than one entry for an attribute, so it can, for example, store a number of email addresses for one person's directory entry all labeled with the attribute "mail"

return_value["count"] = number of values for attribute
return_value[0] = first value of attribute
return_value[i] = ith value of attribute

Esempio 1. List all values of the "mail" attribute for a directory entry

<?php
// $ds is a valid link identifier for a directory server

// $sr is a valid search result from a prior call to
//     one of the ldap directory search calls

// $entry is a valid entry identifier from a prior call to
//        one of the calls that returns a directory entry

$values = ldap_get_values($ds, $entry, "mail");

echo $values["count"] . " email addresses for this entry.<br />";

for ($i=0; $i < $values["count"]; $i++) {
    echo $values[$i] . "<br />";
}
?>

ldap_list

(PHP 3, PHP 4, PHP 5)

ldap_list -- Single-level search

Description

resource ldap_list ( resource link_identifier, string base_dn, string filter [, array attributes [, int attrsonly [, int sizelimit [, int timelimit [, int deref]]]]] )

Returns a search result identifier or FALSE on error.

ldap_list() performs the search for a specified filter on the directory with the scope LDAP_SCOPE_ONELEVEL.

LDAP_SCOPE_ONELEVEL means that the search should only return information that is at the level immediately below the base_dn given in the call. (Equivalent to typing "ls" and getting a list of files and folders in the current working directory.)

This call takes 5 optional parameters. See ldap_search() notes.

Nota: These optional parameters were added in 4.0.2: attrsonly, sizelimit, timelimit, deref.

Esempio 1. Produce a list of all organizational units of an organization

// $ds is a valid link identifier for a directory server

$basedn = "o=My Company, c=US";
$justthese = array("ou");

$sr=ldap_list($ds, $basedn, "ou=*", $justthese);

$info = ldap_get_entries($ds, $sr);

for ($i=0; $i<$info["count"]; $i++) {
    echo $info[$i]["ou"][0] ;
}

Nota: From 4.0.5 on it's also possible to do parallel searches. See ldap_search() for details.

ldap_mod_add

(PHP 3 >= 3.0.8, PHP 4, PHP 5)

ldap_mod_add -- Add attribute values to current attributes

Description

bool ldap_mod_add ( resource link_identifier, string dn, array entry )

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

This function adds attribute(s) to the specified dn. It performs the modification at the attribute level as opposed to the object level. Object-level additions are done by the ldap_add() function.

Nota: Questa funzione è binary-safe (gestisce correttamente i file binari)

ldap_mod_del

(PHP 3 >= 3.0.8, PHP 4, PHP 5)

ldap_mod_del -- Delete attribute values from current attributes

Description

An empty filter is not allowed. If you want to retrieve absolutely all information for this entry, use a filter of "objectClass=*". If you know which entry types are used on the directory server, you might use an appropriate filter such as "objectClass=inetOrgPerson".

This call takes 5 optional parameters. See ldap_search() notes.

Nota: These optional parameters were added in 4.0.2: attrsonly, sizelimit, timelimit, deref.

From 4.0.5 on it's also possible to do parallel searches. See ldap_search() for details.

ldap_rename

(PHP 4 >= 4.0.5, PHP 5)

ldap_rename -- Modify the name of an entry

Description

bool ldap_rename ( resource link_identifier, string dn, string newrdn, string newparent, bool deleteoldrdn )

The entry specified by dn is renamed/moved. The new RDN is specified by newrdn and the new parent/superior entry is specified by newparent. If the parameter deleteoldrdn is TRUE the old RDN value(s) is removed, else the old RDN value(s) is retained as non-distinguished values of the entry. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Nota: This function currently only works with LDAPv3. You may have to use ldap_set_option() prior to binding to use LDAPv3. This function is only available when using OpenLDAP 2.x.x OR Netscape Directory SDK x.x, and was added in PHP 4.0.5.

ldap_sasl_bind

(PHP 5)

ldap_sasl_bind -- Bind to LDAP directory using SASL

Description

bool ldap_sasl_bind ( resource link [, string binddn [, string password [, string sasl_mech [, string sasl_realm [, string sasl_authz_id [, string props]]]]]] )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Requirement: ldap_sasl_bind() requires SASL support (sasl.h). Be sure --with-ldap-sasl is used when configuring PHP otherwise this function will be undefined.

ldap_search

(PHP 3, PHP 4, PHP 5)

ldap_search -- Search LDAP tree

Description

resource ldap_search ( resource link_identifier, string base_dn, string filter [, array attributes [, int attrsonly [, int sizelimit [, int timelimit [, int deref]]]]] )

Returns a search result identifier or FALSE on error.

ldap_search() performs the search for a specified filter on the directory with the scope of LDAP_SCOPE_SUBTREE. This is equivalent to searching the entire directory. base_dn specifies the base DN for the directory.

There is an optional fourth parameter, that can be added to restrict the attributes and values returned by the server to just those required. This is much more efficient than the default action (which is to return all attributes and their associated values). The use of the fourth parameter should therefore be considered good practice.

The fourth parameter is a standard PHP string array of the required attributes, e.g. array("mail", "sn", "cn") Note that the "dn" is always returned irrespective of which attributes types are requested.

Note too that some directory server hosts will be configured to return no more than a preset number of entries. If this occurs, the server will indicate that it has only returned a partial results set. This occurs also if the sixth parameter sizelimit has been used to limit the count of fetched entries.

The fifth parameter attrsonly should be set to 1 if only attribute types are wanted. If set to 0 both attributes types and attribute values are fetched which is the default behaviour.

With the sixth parameter sizelimit it is possible to limit the count of entries fetched. Setting this to 0 means no limit. NOTE: This parameter can NOT override server-side preset sizelimit. You can set it lower though.

The seventh parameter timelimit sets the number of seconds how long is spend on the search. Setting this to 0 means no limit. NOTE: This parameter can NOT override server-side preset timelimit. You can set it lower though.

The eighth parameter deref specifies how aliases should be handled during the search. It can be one of the following:

LDAP_DEREF_NEVER - (default) aliases are never dereferenced.
LDAP_DEREF_SEARCHING - aliases should be dereferenced during the search but not when locating the base object of the search.
LDAP_DEREF_FINDING - aliases should be dereferenced when locating the base object but not during the search.
LDAP_DEREF_ALWAYS - aliases should be dereferenced always.

Nota: These optional parameters were added in 4.0.2: attrsonly, sizelimit, timelimit, deref.

The search filter can be simple or advanced, using boolean operators in the format described in the LDAP documentation (see the Netscape Directory SDK for full information on filters).

The example below retrieves the organizational unit, surname, given name and email address for all people in "My Company" where the surname or given name contains the substring $person. This example uses a boolean filter to tell the server to look for information in more than one attribute.
Esempio 1. LDAP search
<?php // $ds is a valid link identifier for a directory server // $person is all or part of a person's name, eg "Jo" $dn = "o=My Company, c=US"; $filter="(|(sn=$person*)(givenname=$person*))"; $justthese = array("ou", "sn", "givenname", "mail"); $sr=ldap_search($ds, $dn, $filter, $justthese); $info = ldap_get_entries($ds, $sr); echo $info["count"]." entries returned\n"; ?>

From 4.0.5 on it's also possible to do parallel searches. To do this you use an array of link identifiers, rather than a single identifier, as the first argument. If you don't want the same base DN and the same filter for all the searches, you can also use an array of base DNs and/or an array of filters. Those arrays must be of the same size as the link identifier array since the first entries of the arrays are used for one search, the second entries are used for another, and so on. When doing parallel searches an array of search result identifiers is returned, except in case of error, then the entry corresponding to the search will be FALSE. This is very much like the value normally returned, except that a result identifier is always returned when a search was made. There are some rare cases where the normal search returns FALSE while the parallel search returns an identifier.

ldap_set_option

(PHP 4 >= 4.0.4, PHP 5)

ldap_set_option -- Set the value of the given option

Description

bool ldap_set_option ( resource link_identifier, int option, mixed newval )

Sets the value of the specified option to be newval. Restituisce TRUE in caso di successo, FALSE in caso di fallimento. on error.

The parameter option can be one of: LDAP_OPT_DEREF, LDAP_OPT_SIZELIMIT, LDAP_OPT_TIMELIMIT, LDAP_OPT_PROTOCOL_VERSION, LDAP_OPT_ERROR_NUMBER, LDAP_OPT_REFERRALS, LDAP_OPT_RESTART, LDAP_OPT_HOST_NAME, LDAP_OPT_ERROR_STRING, LDAP_OPT_MATCHED_DN, LDAP_OPT_SERVER_CONTROLS, LDAP_OPT_CLIENT_CONTROLS. Here's a brief description, see draft-ietf-ldapext-ldap-c-api-xx.txt for details.

The options LDAP_OPT_DEREF, LDAP_OPT_SIZELIMIT, LDAP_OPT_TIMELIMIT, LDAP_OPT_PROTOCOL_VERSION and LDAP_OPT_ERROR_NUMBER have integer value, LDAP_OPT_REFERRALS and LDAP_OPT_RESTART have boolean value, and the options LDAP_OPT_HOST_NAME, LDAP_OPT_ERROR_STRING and LDAP_OPT_MATCHED_DN have string value. The first example illustrates their use. The options LDAP_OPT_SERVER_CONTROLS and LDAP_OPT_CLIENT_CONTROLS require a list of controls, this means that the value must be an array of controls. A control consists of an oid identifying the control, an optional value, and an optional flag for criticality. In PHP a control is given by an array containing an element with the key oid and string value, and two optional elements. The optional elements are key value with string value and key iscritical with boolean value. iscritical defaults to FALSE if not supplied. See also the second example below.

Nota: This function is only available when using OpenLDAP 2.x.x OR Netscape Directory SDK x.x, and was added in PHP 4.0.4.

ldap_unbind() function unbinds from the LDAP directory.

LXIV. libxml Functions

Introduzione

These functions/constants are available since PHP 5.1.0 and if you have compiled one of the extensions based on libxml, like DOM, SimpleXML and XSLT.

Requisiti

This extension requires libxml >= 2.6.0.

Classi predefinite

LibXMLError

Proprietà

code - the error's code
column - the column where the error occurred. Please note that this property isn't entirely implemented in libxml and therefore 0 is often returned.
file - the filename, or empty if the XML was loaded from a string
level - the severity of the error (one of the following constants: LIBXML_ERR_WARNING, LIBXML_ERR_ERROR or LIBXML_ERR_FATAL)
line - the line where the error occurred
message - the error message

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

LIBXML_COMPACT (integer): Activate small nodes allocation optimization. This may speed up your application without needing to change the code.
Nota: Only available in Libxml >= 2.6.21
LIBXML_DTDATTR (integer): Default DTD attributes
LIBXML_DTDLOAD (integer): Load the external subset
LIBXML_DTDVALID (integer): Validate with the DTD
LIBXML_NOBLANKS (integer): Remove blank nodes
LIBXML_NOCDATA (integer): Merge CDATA as text nodes
LIBXML_NOEMPTYTAG (integer): Expand empty tags (e.g. <br/> to <br></br>)
Nota: This option is currently just available in the DOMDocument->save() and DOMDocument->saveXML() functions.
LIBXML_NOENT (integer): Substitute entities
LIBXML_NOERROR (integer): Suppress error reports
LIBXML_NONET (integer): Disable network access when loading documents
LIBXML_NOWARNING (integer): Suppress warning reports
LIBXML_NOXMLDECL (integer): Drop the XML declaration when saving a document
Nota: Only available in Libxml >= 2.6.21
LIBXML_NSCLEAN (integer): Remove redundant namespaces declarations
LIBXML_XINCLUDE (integer): Implement XInclude substitution
LIBXML_ERR_ERROR (integer): A recoverable error
LIBXML_ERR_FATAL (integer): A fatal error
LIBXML_ERR_NONE (integer): No errors
LIBXML_ERR_WARNING (integer): A simple warning
LIBXML_VERSION (integer): libxml version like 20605 or 20617
LIBXML_DOTTED_VERSION (string): libxml version like 2.6.5 or 2.6.17

Sommario
libxml_clear_errors -- Clear libxml error buffer
libxml_get_errors -- Retrieve array of errors
libxml_get_last_error -- Retrieve last error from libxml
libxml_set_streams_context -- Set the streams context for the next libxml document load or write
libxml_use_internal_errors -- Disable libxml errors and allow user to fetch error information as needed

libxml_clear_errors

(PHP 5 >= 5.1.0RC1)

libxml_clear_errors -- Clear libxml error buffer

Descrizione

void libxml_clear_errors ( void )

libxml_clear_errors() clears the libxml error buffer.

Valori restituiti

No value is returned.

Vedere anche:

libxml_get_errors()

libxml_get_last_error()

libxml_get_errors

(PHP 5 >= 5.1.0RC1)

libxml_get_errors -- Retrieve array of errors

Descrizione

array libxml_get_errors ( void )

Retrieve array of errors.

Valori restituiti

Returns an array with LibXMLError objects if there are any errors in the buffer, or an empty array otherwise.

Esempi

Esempio 1. A libxml_get_errors() example
This example demonstrates how to build a simple libxml error handler.
<?php libxml_use_internal_errors(true); $xmlstr = <<< XML <?xml version='1.0' standalone='yes'?> <movies> <movie> <titles>PHP: Behind the Parser</title> </movie> </movies> XML; $doc = simplexml_load_string($xmlstr); $xml = explode("\n", $xmlstr); if (!$doc) { $errors = libxml_get_errors(); foreach ($errors as $error) { echo display_xml_error($error, $xml); } libxml_clear_errors(); } function display_xml_error($error, $xml) { $return = $xml[$error->line - 1] . "\n"; $return .= str_repeat('-', $error->column) . "^\n"; switch ($error->level) { case LIBXML_ERR_WARNING: $return .= "Warning $error->code: "; break; case LIBXML_ERR_ERROR: $return .= "Error $error->code: "; break; case LIBXML_ERR_FATAL: $return .= "Fatal Error $error->code: "; break; } $return .= trim($error->message) . "\n Line: $error->line" . "\n Column: $error->column"; if ($error->file) { $return .= "\n File: $error->file"; } return "$return\n\n--------------------------------------------\n\n"; } ?>
Il precedente esempio visualizzerà:
<titles>PHP: Behind the Parser</title> ^ Fatal Error 76: Opening and ending tag mismatch: titles line 4 and title Line: 4 Column: 0 --------------------------------------------

Vedere anche:

libxml_get_last_error()

libxml_clear_errors()

libxml_get_last_error

(PHP 5 >= 5.1.0RC1)

libxml_get_last_error -- Retrieve last error from libxml

Descrizione

LibXMLError libxml_get_last_error ( void )

Retrieve last error from libxml.

Valori restituiti

Returns a LibXMLError object if there is any error in the buffer, FALSE otherwise.

Vedere anche:

libxml_get_errors()

libxml_clear_errors()

libxml_set_streams_context

(PHP 5)

libxml_set_streams_context -- Set the streams context for the next libxml document load or write

Descrizione

void libxml_set_streams_context ( resource streams_context )

Sets the streams context for the next libxml document load or write.

Elenco dei parametri

streams_context: The stream context resource (created with stream_context_create())

Valori restituiti

No value is returned.

Esempi

Esempio 1. A libxml_set_streams_context() example
<?php $opts = array( 'http' => array( 'user_agent' => 'PHP libxml agent', ) ); $context = stream_context_create($opts); libxml_set_streams_context($context); // request a file through HTTP $doc = DOMDocument::load('http://www.example.com/file.xml'); ?>

Vedere anche:

stream_context_create()

libxml_use_internal_errors

(PHP 5 >= 5.1.0RC1)

libxml_use_internal_errors -- Disable libxml errors and allow user to fetch error information as needed

Descrizione

bool libxml_use_internal_errors ( [bool use_errors] )

libxml_use_internal_errors() allows you to disable standard libxml errors and enable user error handling.

Elenco dei parametri

use_errors: Whether to enable user error handling. Defaults to FALSE.

Valori restituiti

This function returns the previous value of use_errors.

Esempi

Esempio 1. A libxml_use_internal_errors() example
This example demonstrates the basic usage of libxml errors and the value returned by this function.
<?php // enable user error handling var_dump(libxml_use_internal_errors(true)); $doc = DOMDocument::load('file.xml'); if (!$doc) { $errors = libxml_get_errors(); foreach ($errors as $error) { // handle errors here } libxml_clear_errors(); } ?>
Il precedente esempio visualizzerà:
bool(false)

Vedere anche:

libxml_clear_errors()

libxml_get_errors()

LXV. Lotus Notes Functions

Introduzione

Avvertimento

Nota: Questo modulo è stato spostato nel repository PECL e non sarà più rilascio con il PHP dalla versione 5.0.0. Additional information such as new releases, downloads, source files, maintainer information, and a CHANGELOG, can be located here: http://pecl.php.net/package/notes.

Avvertimento

This extension is currently not supported, thus looking for a maintainer.

Sommario
notes_body -- Open the message msg_number in the specified mailbox on the specified server (leave serv
notes_copy_db -- Copy a Lotus Notes database
notes_create_db -- Create a Lotus Notes database
notes_create_note -- Create a note using form form_name
notes_drop_db -- Drop a Lotus Notes database
notes_find_note -- Returns a note id found in database_name
notes_header_info -- Open the message msg_number in the specified mailbox on the specified server (leave serv
notes_list_msgs -- Returns the notes from a selected database_name
notes_mark_read -- Mark a note_id as read for the User user_name
notes_mark_unread -- Mark a note_id as unread for the User user_name
notes_nav_create -- Create a navigator name, in database_name
notes_search -- Find notes that match keywords in database_name
notes_unread -- Returns the unread note id's for the current User user_name
notes_version -- Get the version Lotus Notes

LXVI. Funzioni LZF

Introduzione

LZF è un algoritmo di compressione molto veloce, ideale per risparmiare spazio con leggere perdite di velocità. L'algoritmo può essere ottimizzato per velocità o spazio al momento della compila.

Installazione

Per potere utilizzare queste funzioni occorre compilare il PHP con il supporto lzf utilizzando il parametro di configurazione --with-lzf[=DIR]. Occorre, inoltre, indicare --enable-lzf-better-compression per abilitare l'ottimizzazione per lo spazio piuttosto che per la velocità

Gli utenti di Windows devono abilitare php_lzf.dll dal php.ini per potere utilizzare queste funzioni. You may download this PECL extension DLL from the PHP Downloads page or at http://snaps.php.net/.

Sommario
lzf_compress -- Compression LZF.
lzf_decompress -- Decompressione LZF.
lzf_optimized_for -- Determina il tipo di ottimizzazione del modulo LZF.

lzf_compress

(PECL)

lzf_compress -- Compression LZF.

Descrizione

string lzf_compress ( string arg )

lzf_compress() comprime i dati presenti nel parametro arg.

Restituisce i dati compressi oppre FALSE se si verifica un errore.

Vedere anche lzf_decompress().

lzf_decompress

(PECL)

lzf_decompress -- Decompressione LZF.

Descrizione

string lzf_decompress ( string arg )

lzf_decompress() decomprime i dati dal parametro arg.

Restituisce id ati decompressi oppure FALSE se si verifica un errore.

Vedere anche lzf_compress().

lzf_optimized_for

(PECL)

lzf_optimized_for -- Determina il tipo di ottimizzazione del modulo LZF.

Descrizione

int lzf_optimized_for ( void )

Restituisce 1 se LZF è ottimizzato per la velocità, 0 per la compressione.

LXVII. Funzioni di Mail

Introduzione

La funzione mail() permette di inviare messaggi di posta elettronica.

Requisiti

Per avere disponibili le funzioni Mail, il PHP deve potere accedere all'eseguibile sendmail del sistema durante la compila. Qualora si utilizzi un'altro programma di posta, tipo qmail o postfix, occorre utlizzare il wrapper sendmail allegato al programma di posta. Il PHP cercherà sendmail in PATH e quindi in: /usr/bin:/usr/sbin:/usr/etc:/etc:/usr/ucblib:/usr/lib. Si consiglia vivamente di avere sendmail in PATH. Inoltre, l'utente che compila PHP deve avere i diritti di accesso all'eseguibile di sendmail.

Installazione

Non è necessaria nessuna installazione per usare queste funzioni, esse fanno parte del core di PHP.

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

Tabella 1. Opzioni di configurazione Mail

Nome	Predefinito	Modificabile in
SMTP	"localhost"	PHP_INI_ALL
smtp_port	"25"	PHP_INI_ALL
sendmail_from	NULL	PHP_INI_ALL
sendmail_path	DEFAULT_SENDMAIL_PATH	PHP_INI_SYSTEM

Per ulteriori dettagli e per la definizione delle costanti PHP_INI_* fare riferimento a ini_set().

Breve descrizione dei parametri di configurazione.

SMTP string

Usato solo sotto Windows: Nome DNS o indirizzo IP del server SMTP che PHP deve usare per spedire posta elettronica con la funzione mail().

smtp_port int

Usato solo sotto Windows: Numero della porta del server specificato da SMTP al quale connettersi quando si inviano email usando mail(); il valore predefinito è 25. Disponibile solo a partire da PHP 4.3.0.

sendmail_from string

Quale campo "From:" devono avere i messaggi inviati da PHP sotto Windows.

sendmail_path string

Dove trovare il programma sendmail, solitamente /usr/sbin/sendmail oppure /usr/lib/sendmail. configure cerca di trovare il file e lo imposta di default, ma se non riesce a localizzarlo, lo si può impostare qui.

I sistemi che non usano sendmail devono impostare questa direttiva al wrapper che i rispettivi sistemi di posta offrono, se esistenti. Per esempio, gli utenti di Qmail possono normalmente impostarla a /var/qmail/bin/sendmail o /var/qmail/bin/qmail-inject.

qmail-inject non necessita di nessuna opzione al fine di processare correttamente la mail.

Questi parametri funzionano anche su Windows. Se si impostate smtp, smtp_port e sendmail_from saranno ignorate e verrà eseguito il comando indicato.

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

Questa estensione non definisce alcuna costante.

Sommario
ezmlm_hash -- Calcola il valore hash che occorre a EZMLM
mail -- Invio mail

ezmlm_hash

(PHP 3 >= 3.0.17, PHP 4 >= 4.0.2, PHP 5)

ezmlm_hash -- Calcola il valore hash che occorre a EZMLM

Descrizione

int ezmlm_hash ( string addr )

ezmlm_hash() calcola il valore hash che occorre quando si mantengono mailing list EZMLM in un database MySQL.

Esempio 1. Calcolare l'hash e iscrivere un utente
<?php $utente = "pippo@example.com"; $hash = ezmlm_hash($utente); $query = sprintf("INSERT INTO esempio VALUES (%s, '%s')", $hash, $utente); $db->query($query); // tramite l'interfaccia db PHPLIB ?>

mail

(PHP 3, PHP 4, PHP 5)

mail -- Invio mail

Descrizione

bool mail ( string a, string oggetto, string messaggio [, string header_addizionali [, string parametri_addizionali]] )

mail() invia automaticamente il messaggio specificato in messaggio al destinatario specificato in a. Destinatari multipli possono essere specificati mettendo una virgola tra ogni indirizzo in a. Email con allegati e tipi speciali di contenuto possono essere spedite usando questa funzione. Questo è possibile tramite la codifica MIME. Per maggiori informazioni, fare riferimento a un articolo Zend o alle Classi Mime del PEAR.

Le seguenti RFC possono essere di aiuto: RFC 1896, RFC 2045, RFC 2046, RFC 2047, RFC 2048 e RFC 2049.

mail() restituisce TRUE se la mail è stata accettata per la spedizione con successo, altrimenti restituisce FALSE.

Avvertimento

L'implementazione Windows della funzione mail() differisce sotto molti aspetti dall'implementazione Unix. Primo, non usa una un programma in locale per comporre i messaggi, ma opera soltanto direttamente sui socket, il che significa che deve essere presente in ascolto un MTA su un socket di rete (che può essere su localhost o su una macchina remota). Secondo, gli header custom quali From:, Cc:, Bcc: e Date: non vengono interpretati subito dal MTA, ma ne viene fatto prima il parsing da parte di PHP. PHP < 4.3 supportava solo gli header Cc: (ed era case-sensitive). PHP >= 4.3 supporta tutti gli header e non è più case-sensitive.

Esempio 1. Inviare mail.
<?php mail("pippo@example.com", "Oggetto", "Linea 1\nLinea 2\nLinea 3"); ?>

Se viene passata come parametro una quarta stringa, questa stringa viene inserita alla fine dell'intestazione (header). Ciò viene tipicamente usato per aggiungere intestazioni supplementari. Intestazioni multiple supplementari sono separate da un carattere di "a capo" (sia newline che carriage return).

Nota: È necessario usare \r\n per separare le intestazioni, alcuni mail transfer agent sotto Unix potrebbero funzionare anche solo con un singolo newline (\n).

Esempio 2. Invio di mail con intestazioni supplementari.
<?php mail("nessuno@example.com", "oggetto", $messaggio, "From: webmaster@{$_SERVER['SERVER_NAME']}\r\n" . "Reply-To: webmaster@{$_SERVER['SERVER_NAME']}\r\n" . "X-Mailer: PHP/" . phpversion()); ?>

Con il parametro parametri_addizionali è possibile impostare un parametro addizionale a linea di comando per il programma configurato per inviare mail usando sendmail_path. Per esempio si può impostare il corretto valore per envelope sender di sendmail con l'opzione -f di sendmail. Potrebbe essere necessario aggiungere l'utente che ha in esecuzione il server web alla configurazione di sendmail per prevenire l'aggiunta dell'intestazione 'X-Warning' quando si imposta envelope sender in questo modo.
Esempio 3. Invio di mail con intestazioni supplementari e impostazione dei parametri addizionali a linea di comando.
<?php mail("nessuno@example.com", "oggetto", $messaggio, "From: webmaster@{$_SERVER['SERVER_NAME']}", "-fwebmaster@{$_SERVER['SERVER_NAME']}"); ?>

Nota: Questo quinto parametro è stato aggiunto in PHP 4.0.5. A partire da PHP 4.2.3, questo parametro è disabilitato in modalità safe_mode, se si cerca di usarlo comunque, la funzione mail() darà un messaggio di errore e restituirà FALSE.

È possibile costruire messaggi complessi utilizzando la tecnica di concatenazione delle stringhe.
Esempio 4. Invio di mail complessa.
<?php /* destinatari */ $destinatari = "Maria <maria@example.com>" . ", " ; // notare la virgola $destinatari .= "Enrica <enrica@example.com>"; /* oggetto */ $oggetto = "Promemoria compleanni di Agosto"; /* messaggio */ $messaggio = ' <html> <head> <title>Promemoria compleanni di Agosto</title> </head> <body> <p>Questi sono i compleanni di Agosto!</p> <table> <tr> <th>Persona</th><th>Giorno</th><th>Mese</th><th>Anno</th> </tr> <tr> <td>Walter</td><td>11</td><td>Agosto</td><td>1946</td> </tr> <tr> <td>Sara</td><td>14</td><td>Agosto</td><td>1985</td> </tr> </table> </body> </html> '; /* Per inviare email in formato HTML, si deve impostare l'intestazione Content-type. */ $intestazioni = "MIME-Version: 1.0\r\n"; $intestazioni .= "Content-type: text/html; charset=iso-8859-1\r\n"; /* intestazioni addizionali */ $intestazioni .= "To: Mary <mary@example.com>, Kelly <kelly@example.com>\r\n"; $intestazioni .= "From: Promemoria Compleanni <compleanni@example.com>\r\n"; $intestazioni .= "Cc: archiviocompleanni@example.com\r\n"; $intestazioni .= "Bcc: controllocompleanni@example.com\r\n"; /* ed infine l'invio */ mail($destinatari, $oggetto, $messaggio, $intestazioni); ?>

Nota: Assicurarsi di non avere nessun carattere di newline nei parametri a o oggetto, o la mail non verrà spedita correttamente.

Nota: Il parametro a non può essere un indirizzo nella forma "Qualcosa <qualcuno@example.com>". Il comando di mail non sarebbe in grado di effettuare correttamente il parsing mentre dialoga con il MTA (in particolare sotto Windows).

array mailparse_uudecode_all ( resource fp )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Returns an array listing filename information.

LXIX. Funzioni Matematiche

Introduzione

Queste funzioni matematiche operano esclusivamente nel range dei tipi di dato integer e float del computer. (questo corrisponde attualmente ai tipi di dati long e double del C) Se si ha necessità di lavorare con numeri più grandi, fare riferimento alle funzioni matematiche a precisione arbitraria.

Vedere anche il manuale alle pagine operatori aritmetici.

Requisiti

Non sono necessarie librerie esterne per utilizzare questo modulo.

Installazione

Non è necessaria nessuna installazione per usare queste funzioni, esse fanno parte del core di PHP.

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

Le costanti qui elencate sono sempre disponibili in quanto parte del core di PHP.

Tabella 1. Costanti Matematiche

Costante	Valore	Descrizione
M_PI	3.14159265358979323846	Pi
M_E	2.7182818284590452354	e
M_LOG2E	1.4426950408889634074	log_2 e
M_LOG10E	0.43429448190325182765	log_10 e
M_LN2	0.69314718055994530942	log_e 2
M_LN10	2.30258509299404568402	log_e 10
M_PI_2	1.57079632679489661923	pi/2
M_PI_4	0.78539816339744830962	pi/4
M_1_PI	0.31830988618379067154	1/pi
M_2_PI	0.63661977236758134308	2/pi
M_SQRTPI	1.77245385090551602729	sqrt(pi) [4.0.2]
M_2_SQRTPI	1.12837916709551257390	2/sqrt(pi)
M_SQRT2	1.41421356237309504880	sqrt(2)
M_SQRT3	1.73205080756887729352	sqrt(3) [4.0.2]
M_SQRT1_2	0.70710678118654752440	1/sqrt(2)
M_LNPI	1.14472988584940017414	log_e(pi) [4.0.2]
M_EULER	0.57721566490153286061	Costante di Eulero [4.0.2]

Soltanto M_PI è disponibile nelle versioni precedenti alla PHP 4.0.0 (compresa). Tutte le rimanenti costanti sono disponibili a partire dal PHP 4.0.0. Le costanti indicate con [4.0.2] sono state aggiunte nel PHP 4.0.2.

Sommario
abs -- Valore assoluto
acos -- Arco coseno
acosh -- Inverso del coseno iperbolico
asin -- Arco seno
asinh -- Inverso del seno iperbolico
atan2 -- Arco tangente di due variabili
atan -- Arco tangente
atanh -- Inverso della tangente iperbolica
base_convert -- Converte un numero fra basi arbitrarie
bindec -- Da binario a decimale
ceil -- arrotonda le frazioni all'intero superiore
cos -- Coseno
cosh -- Coseno iperbolico
decbin -- Da decimale a binario
dechex -- Da decimale a esadecimale
decoct -- Da decimale a ottale
deg2rad -- Converte il numero dato in gradi nell'equivalente espresso in radianti
exp -- Calcola l'esponente di e (la base logaritmica naturale o di Nepero)
expm1 -- Restituisce exp(numero) - 1, computato in maniera tale da essere accurato anche se il valore del numero è vicino a zero
floor -- Arrotonda le frazioni all'intero inferiore
fmod -- Returns the floating point remainder (modulo) of the division of the arguments
getrandmax -- Mostra il più grande numero casuale disponibile
hexdec -- Da esadecimale a decimale
hypot -- Restituisce sqrt(num1*num1 + num2*num2)
is_finite -- Verifica se un numero dato è un numero finito
is_infinite -- Verifica se un dato valore è infinito
is_nan -- Verifica se un dato valore non sia un numero
lcg_value -- Generatore combinato lineare congruenziale
log10 -- Logaritmo base-10
log1p -- Restituisce log(1 + numero), computato in maniera tale da essere accurato anche se il valore del numero è vicino a zero
log -- Logaritmo naturale
max -- Trova il valore massimo
min -- Trova il valore minimo
mt_getrandmax -- Mostra il più grande valore casuale disponibile
mt_rand -- Genera un valore casuale migliore
mt_srand -- Inizializza un generatore di numeri casuali migliore
octdec -- Da ottale a decimale
pi -- Restituisce il valore di pi
pow -- Espressione esponenziale
rad2deg -- Converte un numero in radianti nell'equivalente numero in gradi
rand -- Genera un valore casuale
round -- Arrotonda un numero non intero
sin -- Seno
sinh -- Seno iperbolico
sqrt -- Radice quadrata
srand -- inizializza il generatore di numeri casuali
tan -- Tangente
tanh -- Tangente iperbolica

abs

(PHP 3, PHP 4, PHP 5)

abs -- Valore assoluto

Descrizione

number abs ( mixed numero )

Restituisce il valore assoluto di un numero. Se l'argomento della funzione è di tipo float, il valore restituito è float, altrimenti restituisce un integer (perché float di solito ha un range di valori più grande di integer).

Esempio 1. Esempio di abs()

<?php
$abs = abs(-4.2); // $abs = 4.2; (double/float)
$abs2 = abs(5);   // $abs2 = 5; (integer)
$abs3 = abs(-5);  // $abs3 = 5; (integer)
?>

acos

(PHP 3, PHP 4, PHP 5)

acos -- Arco coseno

Descrizione

float acos ( float arg )

Restituisce l'arco coseno di arg in radianti. La funzione acos() è complementare alla funzione cos(), ovvero che a==cos(acos(a)) per ciascun valore di a nel range di acos().

Vedere anche: acosh(), asin() e atan().

acosh

(PHP 4 >= 4.1.0, PHP 5)

acosh -- Inverso del coseno iperbolico

Descrizione

float acosh ( float arg )

Restituisce l'inverso del coseno iperbolico di arg, cioè il valore il cui coseno iperbolico vale arg.

Nota: Questa funzione non è implementata su piattaforme Windows

Vedere anche acos(), asinh() e atanh().

asin

(PHP 3, PHP 4, PHP 5)

asin -- Arco seno

Descrizione

float exp ( float arg )

Restituisce e elevato alla potenza di arg.

Nota: 'e' è la base del sistema dei logaritmi dei numeri naturali, e vale 2.718282.

Esempio 1. Esempio per exp()
<?php echo exp(12) . "\n"; echo exp(5.7); ?>
L'esempio precedente visualizzerà:
1.6275E+005 298.87

Vedere anche log() e pow().

expm1

(PHP 4 >= 4.1.0, PHP 5)

expm1 -- Restituisce exp(numero) - 1, computato in maniera tale da essere accurato anche se il valore del numero è vicino a zero

Description

float expm1 ( float number )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Nota: Questa funzione non è implementata su piattaforme Windows

floor

(PHP 3, PHP 4, PHP 5)

floor -- Arrotonda le frazioni all'intero inferiore

Descrizione

float floor ( float numero )

Restituisce il primo intero più piccolo di numero, se necessario. Il valore restituito da floor() è ancora di tipo float, poiché la gamma di valori del tipo float è solitamente più grande di quella del tipo integer.

Esempio 1. Esempio di floor()
<?php echo floor(4.3); // 4 echo floor(9.999); // 9 ?>

Vedere anche ceil() e round().

fmod

(PHP 4 >= 4.2.0, PHP 5)

fmod -- Returns the floating point remainder (modulo) of the division of the arguments

Description

float fmod ( float x, float y )

Returns the floating point remainder of dividing the dividend (x) by the divisor (y). The reminder (r) is defined as: x = i * y + r, for some integer i. If y is non-zero, r has the same sign as x and a magnitude less than the magnitude of y.

Esempio 1. Using fmod()
<?php $x = 5.7; $y = 1.3; $r = fmod($x, $y); // $r equals 0.5, because 4 * 1.3 + 0.5 = 5.7 ?>

getrandmax

(PHP 3, PHP 4, PHP 5)

getrandmax -- Mostra il più grande numero casuale disponibile

Descrizione

int getrandmax ( void )

Restituisce il valore massimo che può essere restituito da una chiamata alla funzione rand().

Vedere anche rand(), srand() e mt_getrandmax().

hexdec

(PHP 3, PHP 4, PHP 5)

hexdec -- Da esadecimale a decimale

Descrizione

int hexdec ( string stringa_esadecimale )

Restituisce l'equivalente decimale di un numero esadecimale rappresentato dall'argomento stringa_esadecimale. hexdec() converte una stringa esadecimale in un numero decimale. Il più grande numero che può essere convertito è 7fffffff o 2147483647 espresso in decimale.

hexdec() ignora i caratteri non esadecimali che incontra.
Esempio 1. esempio di hexdec()
<?php var_dump(hexdec("See")); var_dump(hexdec("ee")); // entrambi stampano "int(238)" var_dump(hexdec("that")); // stampa "int(10)" var_dump(hexdec("a0")); // stampa "int(160)" ?>

Vedere anche dechex(), bindec(), octdec() e base_convert().

hypot

(PHP 4 >= 4.1.0, PHP 5)

hypot -- Restituisce sqrt(num1*num1 + num2*num2)

Descrizione

float hypot ( float num1, float num2 )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

is_finite

(PHP 4 >= 4.2.0, PHP 5)

is_finite -- Verifica se un numero dato è un numero finito

Descrizione

bool is_finite ( float val )

Restituisce TRUE se val è un numero finito valido all'interno del range dei float, come definito da PHP su questa piattaforma.

Vedere anche is_infinite() e is_nan().

is_infinite

(PHP 4 >= 4.2.0, PHP 5)

is_infinite -- Verifica se un dato valore è infinito

Descrizione

bool is_infinite ( float val )

Restituisce TRUE se val è infinito (positivo o negativo), come il risultato di log(0) o ogni altro valore troppo grande per essere contenuto nel range dei float di una determinata piattaforma.

Vedere anche is_finite() e is_nan().

is_nan

(PHP 4 >= 4.2.0, PHP 5)

is_nan -- Verifica se un dato valore non sia un numero

Descrizione

bool is_nan ( float val )

Restituisce TRUE se val 'non è un numero', come il risultato di acos(1.01).

Vedere anche is_finite() e is_infinite().

lcg_value

(PHP 4, PHP 5)

lcg_value -- Generatore combinato lineare congruenziale

Descriztione

float lcg_value ( void )

lcg_value() restituisce uno pseudo numero casuale nell'intervallo (0, 1). La funzione combina due GC con periodo di 2^31 - 85 e 2^31 - 249. Il periodo di questa funzione è uguale al prodotto dei due primi.

log10

(PHP 3, PHP 4, PHP 5)

log10 -- Logaritmo base-10

Descrizione

float log10 ( float arg )

Restituisce il logaritmo in base-10 di arg.

Vedere anche: log()

log1p

(PHP 4 >= 4.1.0, PHP 5)

log1p -- Restituisce log(1 + numero), computato in maniera tale da essere accurato anche se il valore del numero è vicino a zero

Description

float log1p ( float number )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Nota: Questa funzione non è implementata su piattaforme Windows

log

(PHP 3, PHP 4, PHP 5)

log -- Logaritmo naturale

Descrizione

float log ( float arg [, float base] )

Se si specifica il parametro opzionale base, la funzione log() restituisce log_base arg, altrimenti log() il logaritmo naturale di arg.

Nota: Il parametro base è disponibile dalla versione 4.3.0 di PHP.
Si può comunque calcolare il logaritmo in base b di un numero n, usando la formula matematica: log_b(n) = log(n)/log(b), dove log è il logaritmo neperiano (o naturale).

Vedere anche exp().

max

(PHP 3, PHP 4, PHP 5)

max -- Trova il valore massimo

Descrizione

mixed max ( number arg1, number arg2 [, number ...] )

mixed max ( array numbers [, array ...] )

max() restituisce il numericamente più grande dei valori dati come parametro.

Se il primo ed unico parametro è un array, max() restituisce il massimo dei valori di tale array. Se il primo parametro è un integer, string o double, si ha bisogno almeno di due parametri e max() restituisce il maggiore di tali valori. Si può confrontare un numero illimitato di valori.

Nota: Le stringhe non numeriche saranno considerate dal PHP come 0, ma verrà restituita la stringa se questa è il più alto valore numerico. Se vi sono più argomenti considerati come 0, la funzione max() restituirà il primo (il valore più a sinistra).

Esempio 1. Esempio di max()
<?php echo max(1, 3, 5, 6, 7); // 7 echo max(array(2, 4, 5)); // 5 echo max(0, 'hello'); // 0 echo max('hello', 0); // hello echo max(-1, 'hello'); // hello // Con diversi array, max confronta da sinistra a destra // quindi nell'esempio: 2 == 2, e 4 < 5 $val = max(array(2, 4, 8), array(2, 5, 7)); // array(2, 5, 7) // Nel caso siano forniti array e parametri non array, la funzione restituirà // sempre l'array, considerando questo il più grande $val = max('string', array(2, 5, 7), 42); // array(2, 5, 7) ?>

Vedere anche min() e count().

min

(PHP 3, PHP 4, PHP 5)

min -- Trova il valore minimo

Descrizione

mixed min ( number arg1, number arg2 [, number ...] )

mixed min ( array numbers [, array ...] )

min() restituisce il numericamente più piccolo dei valori dati come parametro.

Se il primo ed unico pareametro è un array, la funzione min() restituisce il valore più basso nell'array. Se il primo parametro è un intero, una stringa, o un float, occorrono almeno due parametri e min() restituisce il minore tra questi. Si può confrontare un numero illimitato di valori.

Nota: Le stringhe non numeriche saranno considerate dal PHP come 0, ma verrà restituita la stringa se questa è il più basso valore numerico. Se vi sono più argomenti considerati come 0, la funzione min() restituirà il primo (il valore più a sinistra).

Esempio 1. Esempio di uso di min()
<?php echo min(2, 3, 1, 6, 7); // 1 echo min(array(2, 4, 5)); // 2 echo min(0, 'hello'); // 0 echo min('hello', 0); // hello echo min('hello', -1); // -1 // Con diversi array, min confronta da sinistra a destra // quindi nell'esempio: 2 == 2, e 4 < 5 $val = min(array(2, 4, 8), array(2, 5, 1)); // array(2, 4, 8) // In caso di parametri misti array e non array, l'array non sarà mai restituito // perchè considerato il più grande $val = min('string', array(2, 5, 7), 42); // string ?>

Vedere anche max() e count().

mt_getrandmax

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

mt_getrandmax -- Mostra il più grande valore casuale disponibile

Descrizione

int mt_getrandmax ( void )

Restituisce il massimo valore che può essere restituito da una chiamata alla funzione mt_rand().

Vedere anche mt_rand(), mt_srand() e getrandmax().

mt_rand

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

mt_rand -- Genera un valore casuale migliore

Descrizione

int mt_rand ( [int min, int max] )

Molti generatori di numeri casuali di vecchie libc hanno caratteristiche dubbie o sconosciute e sono lenti. Di default, PHP usa il generatore di numeri casuali libc con la funzione rand(). La funzione mt_rand() è un sostituto per questa. Usa un generatore di numeri casuali con caratteristiche conosciute, il Mersenne Twister, il quale produce numeri casuali quattro volte più velocemente di libc.

Se invocata senza i parametri opzionali min, max, mt_rand() restituisce un valore pseudo-casuale compreso fra 0 e RAND_MAX. Se ad esempio si desidera un numero casuale compreso fra 5 e 15 (inclusi), usare mt_rand (5, 15).

Esempio 1. Esempio per mt_rand()
<?php echo mt_rand() . "\n"; echo mt_rand() . "\n"; echo mt_rand(5, 15); ?>
L'esempio precedente visualizzerà qualcosa simile a:
1604716014 1478613278 6

Nota: Come in PHP 4.2.0, non vi è necessità di inizializzare il generatore di numeri casuali con srand() oppure con mt_srand() poichè viene eseguito in modo automatico.

Nota: Nelle versioni precedenti la 3.0.7 il significato di max era range. Per ottenere lo stesso risultato in queste vecchie versioni un breve esempio dovrebbe essere il seguente: mt_rand (5, 11), si otterrà un numero casuale compreso fra 5 e 15.

Vedere anche mt_srand(), mt_getrandmax() e rand().

mt_srand

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

mt_srand -- Inizializza un generatore di numeri casuali migliore

Descrizione

void mt_srand ( [int seme] )

Inizializza il generatore di numeri casuali con il parametro seme. A partire dalla versione 4.2.0 di PHP il parametro seme è diventato opzionale, e, per default, viene impostato ad un valore random.

Esempio 1. Esempio di uso di mt_srand()
<?php // inizializza usando i microsecondi function crea_seme() { list($usec, $sec) = explode(' ', microtime()); return (float) $sec + ((float) $usec * 100000); } mt_srand(crea_seme()); $valorecasuale = mt_rand(); ?>

Nota: Come in PHP 4.2.0, non vi è necessità di inizializzare il generatore di numeri casuali con srand() oppure con mt_srand() poichè viene eseguito in modo automatico.

Vedere anche mt_rand(), mt_getrandmax() e srand().

octdec

(PHP 3, PHP 4, PHP 5)

octdec -- Da ottale a decimale

Descrizione

int octdec ( string stringa_ottale )

Restituisce l'equivalente decimale del numero ottale rappresentato dall'argomento stringa_ottale. OctDec converte una stringa ottale in un numero decimale. Il più grande numero che può essere convertito è 17777777777 o 2147483647 in decimale.

Esempio 1. Esempio per octdec()
<?php echo octdec('77') . "\n"; echo octdec(decoct(45)); ?>
L'esempio precedente visualizzerà:
63 45

Vedere anche decoct(), bindec(), hexdec() e base_convert().

pi

(PHP 3, PHP 4, PHP 5)

pi -- Restituisce il valore di pi

Descrizione

double pi ( void )

Restituisce una appossimazione di pi. Il valore restituito è un float e ha precisione secondo la direttiva precision del file php.ini, che ha come valore predefinito 14. Inoltre, si può usare la costante M_PI che permette di ottenere risultati identici all'uso di pi().

Esempio 1. Esempio di uso di pi()
<?php echo pi(); // 3.1415926535898 echo M_PI; // 3.1415926535898 ?>

pow

(PHP 3, PHP 4, PHP 5)

pow -- Espressione esponenziale

Descrizione

float pow ( float base, float esp )

Restituisce base elevato alla potenza di esp. Se possibile, questa funzione restituisce un integer.

Se la potenza non può essere computata, viene generato un errore, e pow() restituirà FALSE. dalla versione 4.2.0 di PHP la funzione pow() non genera alcun warning.

Nota: Il PHP non può gestire valori negativi per bases.

Esempio 1. Alcuni esempi di pow()

<?php

var_dump( pow(2,8)); // int(256)
echo pow(-1, 20); // 1
echo pow(0, 0); // 1

echo pow(-1, 5.5); // errore

?>

Avvertimento

Nel PHP 4.0.6 e precedenti, pow() restituiva sempre un float e non generava alcun errore.

Vedere anche exp() sqrt() bcpow() e gmp_pow().

rad2deg

(PHP 3 >= 3.0.4, PHP 4, PHP 5)

rad2deg -- Converte un numero in radianti nell'equivalente numero in gradi

Descrizione

double rad2deg ( double numero )

Questa funzione converte numero da radianti a gradi.

Esempio 1. Esempio per rad2deg()
<?php echo rad2deg(M_PI_4); // 45 ?>

Vedere anche deg2rad().

rand

(PHP 3, PHP 4, PHP 5)

rand -- Genera un valore casuale

Descrizione

int rand ( [int min, int max] )

Se chiamata senza i parametri opzionali min, max, rand() restituisce un valore pseudo casuale compreso fra 0 e RAND_MAX. Se ad esempio si desidera un numero casuale compreso fra 5 e 15 (inclusi) usare rand (5, 15).

Esempio 1. Esempio per rand()
<?php echo rand() . "\n"; echo rand() . "\n"; echo rand(5, 15); ?>
L'esempio precedente visualizzerà qualcosa simile a:
7771 22264 11

Nota: Su alcune piattaforme (come Windows) RAND_MAX vale soltanto 32768. Se si desidera un range più ampio di 32768, indicare i parametri min e max, questo permette di avere range maggiori di RAND_MAX, oppure si valuti l'utilizzo di mt_rand()

Nota: Come in PHP 4.2.0, non vi è necessità di inizializzare il generatore di numeri casuali con srand() oppure con mt_srand() poichè viene eseguito in modo automatico.

Nota: Nelle versioni precedenti la 3.0.7 il significato di max era range. Per ottenere lo stesso risultato in queste vecchie versioni un breve esempio dovrebbe essere il seguente: rand (5, 11), si otterrà un numero casuale compreso fra 5 e 15.

Vedere anche: srand(), getrandmax() e mt_rand().

round

(PHP 3, PHP 4, PHP 5)

round -- Arrotonda un numero non intero

Descrizione

double round ( double val [, int precisione] )

Restituisce il valore arrotondato di val con la precisione specificata (numero di cifre dopo il punto decimale). precisione può anche essere negativa o zero (predefinito).

Esempio 1. round() examples
<?php echo round(3.4); // 3 echo round(3.5); // 4 echo round(3.6); // 4 echo round(3.6, 0); // 4 echo round(1.95583, 2); // 1.96 echo round(1241757, -3); // 1242000 echo round(5.045, 2); // 5.05 echo round(5.055, 2); // 5.06 ?>

Nota: Il PHP non maneggia correttamente stringhe quali "12,300.2" in maniera predefinita. Fare riferimento a conversione da stringhe.

Nota: Il parametro precisione è disponibile dal PHP 4.

Vedere anche: ceil(), floor() e number_format().

sin

(PHP 3, PHP 4, PHP 5)

sin -- Seno

Descrizione

float sin ( float arg )

La funzione sin() restituisce il seno di arg. Il parametro arg viene espresso in radianti.

Esempio 1. Esempio di uso di sin()
<?php // La precisione dipende dalle direttive di precisione echo sin(deg2rad(60)); // 0.866025403 ... echo sin(60); // -0.304810621 ... ?>

Vedere anche: asin(), cos(), tan() e deg2rad().

sinh

(PHP 4 >= 4.1.0, PHP 5)

sinh -- Seno iperbolico

Descrizione

float sinh ( float arg )

Restituisce il seno iperbolico di arg, definito come (exp(arg) - exp(-arg))/2.

Vedere anche: sin(), asinh(), cos() e tan().

sqrt

(PHP 3, PHP 4, PHP 5)

sqrt -- Radice quadrata

Descrizione

float sqrt ( float arg )

Restituisce la radice quadrata di arg.

Esempio 1. Esempio di uso di sqrt()
<?php // La precisione dipende dalle impostazioni delle direttive sulla precisione echo sqrt(9); // 3 echo sqrt(10); // 3.16227766 ... ?>

Vedere anche pow().

srand

(PHP 3, PHP 4, PHP 5)

srand -- inizializza il generatore di numeri casuali

Descrizione

void srand ( [int seme] )

Inizializza il generatore di numeri casuali con seme. A partire dalla versione 4.2.0 di PHP il parametro seme è opzionale, e per default viene impostato ad un valore casuale.

Esempio 1. Esempio di uso di srand()
<?php // inizializza usando i microsecondi function crea_seme() { list($usec, $sec) = explode(' ', microtime()); return (float) $sec + ((float) $usec * 100000); } srand((double)microtime()*1000000); $valorecasuale = rand(); ?>

Nota: Come in PHP 4.2.0, non vi è necessità di inizializzare il generatore di numeri casuali con srand() oppure con mt_srand() poichè viene eseguito in modo automatico.

Vedere anche: rand(), getrandmax() e mt_srand().

tan

(PHP 3, PHP 4, PHP 5)

tan -- Tangente

Descrizione

float tan ( float arg )

La funzione tan() restituisce la tangente del parametro arg. Il parametro arg deve essere espresso in radianti.

Esempio 1. Esempio per tan()
<?php echo tan(M_PI_2); // 1 ?>

Vedere anche: atan(), sin(), cos() e deg2rad().

tanh

(PHP 4 >= 4.1.0, PHP 5)

tanh -- Tangente iperbolica

Descrizione

float tanh ( float arg )

Restituisce la tangente iperbolica di arg, definita come sinh(arg)/cosh(arg).

Vedere anche: tan(), atanh(), sin() e cos().

LXX. MaxDB PHP Extension

Introduzione

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.mysql.com/products/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://dev.mysql.com/doc/maxdb/.

Requisiti

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://dev.mysql.com/doc/maxdb/.

Download the MaxDB SQLDBC package from http://dev.mysql.com/downloads/maxdb/clients.html.

Installazione

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.

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

Tabella 1. MaxDB Configuration Options

Name	Default	Changeable
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

Per maggiori dettagli sulle costanti PHP_INI_* vedere Appendice G.

Breve descrizione dei parametri di configurazione.

maxdb.default_host string: The default server host to use when connecting to the database server if no other host is specified.
maxdb.default_db string: The default server database to use when connecting if no other database is specified.
maxdb.default_user string: The default user name to use when connecting to the database server if no other name is specified.
maxdb.default_pw string: The default password to use when connecting to the database server if no other password is specified.
maxdb.long_readlen integer: The default maximum length of bytes that is transferred to the client if long data is retrieved from the MaxDB database server.

Classi predefinite

maxdb

Represents a connection between PHP and a MaxDB database.

Costruttori

maxdb - construct a new maxdb object

Metodi

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 a 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 a 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

Proprietà

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.

Metodi

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 a 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

Proprietà

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.

Metodi

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

Proprietà

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

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

The following constants to use with maxdb_options() are defined. For further description of these constants see http://dev.mysql.com/doc/maxdb/.

Tabella 2. MaxDB PHP client constants

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:

Tabella 3. MaxDB fetch constants

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.

Esempi

All examples in the MaxDB PHP documentation use the HOTELDB demo database from MaxDB. More about this database can be found at http://dev.mysql.com/doc/maxdb/en/98/11b83fa6b33c17e10000000a114084/frameset.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.
Esempio 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.
Esempio 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.
Esempio 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); ?>

Sommario
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 di maxdb_stmt_bind_param()
maxdb_bind_result -- Alias di 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 di maxdb_character_set_name()
maxdb_close_long_data -- Alias di 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 di maxdb_real_escape_string()
maxdb_execute -- Alias di 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 di 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 di 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 di maxdb_stmt_param_count()
maxdb_ping -- Pings a server connection, or tries to reconnect if the connection has gone down
maxdb_prepare -- Prepare a 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 a 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 di 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 di 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 a 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

maxdb_affected_rows

(PECL)

maxdb_affected_rows

(no version information, might be only in CVS)

maxdb->affected_rows -- Gets the number of affected rows in a previous MaxDB operation

Description

Procedural style:

int maxdb_affected_rows ( resource link )

Object oriented style (property):

class maxdb {

int affected_rows

}

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.

Nota: 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.

Return Values

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.

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

The above examples would produce the following output:

Affected rows (INSERT): 15
Affected rows (UPDATE): 15
Affected rows (DELETE): 0
Affected rows (SELECT): 15

maxdb_autocommit

(PECL)

maxdb_autocommit

(no version information, might be only in CVS)

maxdb->auto_commit -- Turns on or off auto-commiting database modifications

Description

Procedural style:

bool maxdb_autocommit ( resource link, bool mode )

Object oriented style (method)

class maxdb {

bool auto_commit ( bool mode )

}

maxdb_autocommit() is used to turn on or off auto-commit mode on queries for the database connection represented by the link resource.

Return values

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

Description

Procedural style:

bool maxdb_change_user ( resource link, string user, string password, string database )

Object oriented style (method):

class maxdb {

bool change_user ( string 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.

Nota: 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.

Return Values

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

The above examples would produce the following output:

Result: a
Database running

maxdb_character_set_name

(PECL)

maxdb_character_set_name

(no version information, might be only in CVS)

maxdb->character_set_name -- Returns the default character set for the database connection

Description

Procedural style:

string maxdb_character_set_name ( resource link )

Object oriented style (method):

class maxdb {

string character_set_name ( void )

}

Returns the current character set for the database connection specified by the link parameter.

Return values

The default character set for the current connection, either ascii or unicode.

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

The above examples would be produce the following output:

Current character set is ascii

maxdb_client_encoding

Return values

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

maxdb_commit

(PECL)

maxdb_commit

(no version information, might be only in CVS)

maxdb->commit -- Commits the current transaction

Description

Procedural style:

bool maxdb_commit ( resource link )

Object oriented style (method)

class maxdb {

bool commit ( void )

}

Commits the current transaction for the database connection specified by the link parameter.

Return values

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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.

maxdb_connect_errno

(PECL)

maxdb_connect_errno -- Returns the error code from last connect call

Description

int maxdb_connect_errno ( void )

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.

Return values

An error code value for the last call to maxdb_connect(), if it failed. zero means no error occurred.

Example

Esempio 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()); } ?>

The above example would produce the following output:

PHP Warning:  maxdb_connect(): -4008 POS(1) Unknown user name/password combination [08004] <...>
Can't connect to localhost. Errorcode: -4008

maxdb_connect_error

(PECL)

maxdb_connect_error -- Returns a string description of the last connect error

Description

string maxdb_connect_error ( void )

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.

Return values

A string that describes the error. An empty string if no error occurred.

Example

Esempio 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()); } ?>

The above example would produce the following output:

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

maxdb_connect

(PECL)

maxdb_connect

(no version information, might be only in CVS)

maxdb() -- Open a new connection to the MaxDB server

Description

Procedural style

resource maxdb_connect ( [string host [, string username [, string passwd [, string dbname [, int port [, string socket]]]]]] )

Object oriented style (constructor):

class maxdb {

__construct ( [string host [, string username [, string passwd [, string dbname [, int port [, 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, or FALSE on failure.

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.

Return values

Returns a resource which represents the connection to a MaxDB Server or FALSE if the connection failed.

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

The above examples would produce the following output:

Host information: localhost

maxdb_data_seek

(PECL)

maxdb_data_seek

(no version information, might be only in CVS)

result->data_seek -- Adjusts the result pointer to an arbitary row in the result

Description

Procedural style:

bool maxdb_data_seek ( resource result, int offset )

Object oriented style (method):

class result {

bool data_seek ( int 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).

Return values

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

The above examples would produce the following output:

City: Irvine  State: CA

maxdb_debug

(PECL)

maxdb_debug -- Performs debugging operations

Description

void maxdb_debug ( string 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.

Return values

maxdb_debug() doesn't return any value.

Example

Esempio 1. Procedural style

<?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

(PECL)

maxdb_disable_reads_from_master

(no version information, might be only in CVS)

maxdb->disable_reads_from_master -- Disable reads from master

Description

Procedural style:

bool maxdb_disable_reads_from_master ( resource link )

Object oriented style (method):

maxdb->errno -- Returns the error code for the most recent function call

Description

Procedural style:

int maxdb_errno ( resource link )

Object oriented style (property):

class maxdb {

int errno

}

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.

Return values

An error code value for the last call, if it failed. zero means no error occurred.

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

The above examples would produce the following output:

PHP Warning:  maxdb_query(): -4005 POS(8) Unknown column name:XXX [42000] <...>
Errorcode: -4005

maxdb_error

(PECL)

maxdb_error -- Returns a string description of the last error

Description

Procedural style:

string maxdb_error ( resource link )

Object oriented style (property)

class maxdb {

string error

}

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.

Return values

A string that describes the error. An empty string if no error occurred.

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

The above examples would produce the following output:

PHP Warning:  maxdb_query(): -4005 POS(8) Unknown column name:XXX [42000]
Errormessgae: POS(8) Unknown column name:XXX

maxdb_escape_string

(PECL)

maxdb_escape_string -- Alias di maxdb_real_escape_string()

Descrizione

This function is an alias of: maxdb_real_escape_string().

maxdb_execute

(PECL)

maxdb_execute -- Alias di maxdb_stmt_execute()

Descrizione

This function is an alias of: maxdb_stmt_execute().

This function alias is deprecated and only exists for backwards compatibility reasons. It is recommended to not use this function as one day it may be removed from PHP.

maxdb_fetch_array

(PECL)

maxdb_fetch_array

(no version information, might be only in CVS)

result->fetch_array -- Fetch a result row as an associative, a numeric array, or both

Description

Procedural style:

mixed maxdb_fetch_array ( resource result [, int resulttype] )

Object oriented style (method):

class result {

mixed fetch_array ( [int resulttype] )

}

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.

Nota: I nomi dei campi restituiti da questa funzione sono case-sensitive.

Nota: This function sets NULL fields to PHP NULL value.

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.

Return values

Returns an array that corresponds to the fetched row or NULL if there are no more rows in resultset.

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

The above examples would produce the following output:

New York (NY)
New York (NY)
Long Island (NY)

maxdb_fetch_assoc

(PECL)

maxdb_fetch_assoc

(no version information, might be only in CVS)

maxdb->fetch_assoc -- Fetch a result row as an associative array

Description

Procedural style:

array maxdb_fetch_assoc ( resource result )

Object oriented style (method):

class result {

array fetch_assoc ( void )

}

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.

Nota: I nomi dei campi restituiti da questa funzione sono case-sensitive.

Nota: This function sets NULL fields to PHP NULL value.

Return values

Returns an array that corresponds to the fetched row or NULL if there are no more rows in resultset.

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

The above examples would produce the following output:

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)

maxdb_fetch_field_direct

(PECL)

maxdb_fetch_field_direct

(no version information, might be only in CVS)

result->fetch_field_direct -- Fetch meta-data for a single field

Description

Procedural style:

mixed maxdb_fetch_field_direct ( resource result, int fieldnr )

Object oriented style (method):

class result {

mixed fetch_field_direct ( int fieldnr )

}

maxdb_fetch_field_direct() returns an resource which contains field definition informations from specified resultset. The value of fieldnr must be in the range from 0 to number of fields - 1.

Return values

Returns an resource which contains field definition informations or FALSE if no field information for specified fieldnr is available.

Tabella 1. Object attributes

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)

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

The above examples would produce the following output:

Name:     CNO
Table:
max. Len: 4
Flags:    -1
Type:     0

maxdb_fetch_field

(PECL)

maxdb_fetch_field

(no version information, might be only in CVS)

result->fetch_field -- Returns the next field in the result set

Description

Procedural style:

mixed maxdb_fetch_field ( resource result )

Object oriented style (method):

class result {

mixed fetch_field ( void )

}

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.

Return values

Returns an resource which contains field definition informations or FALSE if no field information is available.

Tabella 1. Object properties

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)

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

The above examples would produce the following output:

Name:     NAME
Table:
max. Len: 10
Flags:    -1
Type:     2

Name:     CNO
Table:
max. Len: 4
Flags:    -1
Type:     0

maxdb_fetch_fields

(PECL)

maxdb_fetch_fields

(no version information, might be only in CVS)

result->fetch_fields -- Returns an array of resources representing the fields in a result set

Description

Procedural Style:

mixed maxdb_fetch_fields ( resource result )

Object oriented style (method):

class result {

mixed fetch_fields ( void )

}

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.

Return values

Returns an array of resources which contains field definition informations or FALSE if no field information is available.

Tabella 1. Object properties

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)

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

The above examples would produce the following output:

Name:     NAME
Table:
max. Len: 10
Flags:    -1
Type:     2

Name:     CNO
Table:
max. Len: 4
Flags:    -1
Type:     0

maxdb_fetch_lengths

(PECL)

maxdb_fetch_lengths

(no version information, might be only in CVS)

result->lengths -- Returns the lengths of the columns of the current row in the result set

Description

Procedural style:

array maxdb_fetch_lengths ( resource result )

Object oriented style (property):

class result {

array lengths

}

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 or FALSE on failure.

Return values

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.

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

The above examples would produce the following output:

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

(PECL)

maxdb_fetch_object

(no version information, might be only in CVS)

result->fetch_object -- Returns the current row of a result set as an object

Description

Procedural style:

object maxdb_fetch_object ( object result )

Object oriented style (method):

class result {

object fetch_object ( void )

}

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.

Return values

Returns an object that corresponds to the fetched row or NULL if there are no more rows in resultset.

Nota: I nomi dei campi restituiti da questa funzione sono case-sensitive.

Nota: This function sets NULL fields to PHP NULL value.

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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 ($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);
?>

The above examples would produce the following output:

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)

maxdb_fetch_row

(PECL)

maxdb_fetch_row

(no version information, might be only in CVS)

result->fetch_row -- Get a result row as an enumerated array

Description

Procedural style:

mixed maxdb_fetch_row ( resource result )

Object oriented style (method):

class result {

mixed fetch_row ( void )

}

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.

Return values

maxdb_fetch_row() returns an array that corresponds to the fetched row or NULL if there are no more rows in result set.

Nota: This function sets NULL fields to PHP NULL value.

Example

Esempio 1. Object oriented style

<?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 ($row = $result->fetch_row()) {
       printf ("%s (%s)\n", $row[0], $row[1]);
   }

   /* free result set */
   $result->close();
}

/* close connection */
$maxdb->close();
?>

Esempio 2. Procedural style

<?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_row($result)) {
       printf ("%s (%s)\n", $row[0], $row[1]);
   }

   /* free result set */
   maxdb_free_result($result);
}

/* close connection */
maxdb_close($link);
?>

The above examples would produce the following output:

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)

maxdb_fetch

(PECL)

maxdb_fetch -- Alias di maxdb_stmt_fetch()

Descrizione

This function is an alias of: maxdb_stmt_fetch().

This function alias is deprecated and only exists for backwards compatibility reasons. It is recommended to not use this function as one day it may be removed from PHP.

maxdb_field_count

(PECL)

maxdb_field_count

(no version information, might be only in CVS)

maxdb->field_count -- Returns the number of columns for the most recent query

Description

Procedural style:

int maxdb_field_count ( resource link )

Object oriented style (method):

class maxdb {

int field_count ( void )

}

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.

Return values

An integer representing the number of fields in a result set

Example

Esempio 1. Object oriented style
<?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(); ?>

Esempio 2. Procedural style
<?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

(PECL)

maxdb_field_seek

(no version information, might be only in CVS)

result->field_seek -- Set result pointer to a specified field offset

Description

Procedural style:

bool maxdb_field_seek ( resource result, int fieldnr )

Object oriented style (method):

class result {

bool field_seek ( int 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.

Nota: To seek to the beginning of a row, pass an offset value of zero.

Return values

maxdb_field_seek() returns previuos value of field cursor.

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

The above examples would produce the following output:

Name:     NAME
Table:
max. Len: 10
Flags:    -1
Type:     2

maxdb_field_tell

(PECL)

maxdb_field_tell

(no version information, might be only in CVS)

result->current_field -- Get current field offset of a result pointer

Description

Procedural style:

int maxdb_field_tell ( resource result )

Object oriented style (property):

class result {

int current_field

}

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().

Valori restituiti

Returns current offset of field cursor.

Vedere anche:

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

The above examples would produce the following output:

Column    1:
Name:     NAME
Table:
max. Len: 10
Flags:    -1
Type:     2

Column    2:
Name:     CNO
Table:
max. Len: 4
Flags:    -1
Type:     0

maxdb_free_result

(PECL)

maxdb_free_result

(no version information, might be only in CVS)

result->free -- Frees the memory associated with a result

Description

Procedural style:

void maxdb_free_result ( resource result )

Object oriented style (method):

class result {

void free ( void )

}

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().

Nota: You should always free your result with maxdb_free_result(), when your result resource is not needed anymore.

Valori restituiti

This function doesn't return any value.

Vedere anche:

maxdb_query(), maxdb_stmt_store_result(), maxdb_store_result(), maxdb_use_result().

maxdb_get_client_info

(PECL)

maxdb_get_client_info -- Returns the MaxDB client version as a string

Description

string maxdb_get_client_info ( void )

The maxdb_get_client_info() function is used to return a string representing the client version being used in the MaxDB extension.

Valori restituiti

A string that represents the MaxDB client library version

Example

Esempio 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()); ?>

The above examples would produce the following output:

Client library version: libSQLDBC <...>

maxdb_get_client_version

(PECL)

maxdb_get_client_version -- Get MaxDB client info

Description

int maxdb_get_client_version ( void )

Returns client version number as an integer.

Return values

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 exits.

Example

Esempio 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()); ?>

The above examples would produce the following output:

Client library version: 7.<...>

maxdb_get_host_info

(PECL)

maxdb_get_host_info

(no version information, might be only in CVS)

maxdb->get_host_info -- Returns a string representing the type of connection used

Description

Procdural style:

string maxdb_get_host_info ( resource link )

Object oriented style (property):

class maxdb {

string host_info

}

The maxdb_get_host_info() function returns a string describing the connection represented by the link parameter is using.

Valori restituiti

A character string representing the server hostname and the connection type.

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

The above examples would produce the following output:

Host info: localhost

maxdb_get_metadata

(PECL)

maxdb_get_metadata -- Alias di maxdb_stmt_result_metadata()

Descrizione

This function is an alias of: maxdb_stmt_result_metadata().

This function alias is deprecated and only exists for backwards compatibility reasons. It is recommended to not use this function as one day it may be removed from PHP.

maxdb_get_proto_info

(PECL)

maxdb_get_proto_info

(no version information, might be only in CVS)

maxdb->protocol_version -- Returns the version of the MaxDB protocol used

Description

Procedural style:

int maxdb_get_proto_info ( resource link )

Object oriented style (property):

class maxdb {

string protocol_version

}

Returns an integer representing the MaxDB protocol version used by the connection represented by the link parameter.

Valori restituiti

Returns an integer representing the protocol version (constant 10).

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

The above examples would produce the following output:

Protocol version: 10

maxdb_get_server_info

(PECL)

maxdb_get_server_info

(no version information, might be only in CVS)

maxdb->server_info -- Returns the version of the MaxDB server

Description

Procedural style:

string maxdb_get_server_info ( resource link )

Object oriented style (property):

class maxdb {

string server_info

}

Returns a string representing the version of the MaxDB server that the MaxDB extension is connected to (represented by the link parameter).

Valori restituiti

A character string representing the server version.

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

The above examples would produce the following output:

Server version: Kernel    7<...>

maxdb_get_server_version

(PECL)

maxdb_get_server_version -- Returns the version of the MaxDB server as an integer

Description

Procedural style:

int maxdb_get_server_version ( resource link )

Object oriented style (property):

class maxdb {

int server_version

}

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).

Valori restituiti

An integer representing the server version.

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

The above examples would produce the following output:

Server version: 7<...>

maxdb_info

(PECL)

maxdb_info

(no version information, might be only in CVS)

maxdb->info -- Retrieves information about the most recently executed query

Description

Procedural style:

string maxdb_info ( resource link )

Object oriented style (property)

class maxdb {

string info

}

The maxdb_info() function returns a string providing information about the last query executed. The nature of this string is provided below:

Tabella 1. Possible maxdb_info return values

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

Nota: Queries which do not fall into one of the above formats are not supported. In these situations, maxdb_info() will return an empty string.

Valori restituiti

A character string representing additional information about the most recently executed query.

Vedere anche:

maxdb_affected_rows(), maxdb_warning_count(), maxdb_num_rows()

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

The above examples would produce the following output:

Records: 25 Duplicates: 0 Warnings: 0

maxdb_init

(PECL)

maxdb_init -- Initializes MaxDB and returns an resource for use with maxdb_real_connect

Description

resource maxdb_init ( void )

Allocates or initializes a MaxDB resource suitable for maxdb_options() and maxdb_real_connect().

Nota: Any subsequent calls to any maxdb function (except maxdb_options()) will fail until maxdb_real_connect() was called.

Valori restituiti

Returns an resource.

Vedere anche:

maxdb_options(), maxdb_close(), maxdb_real_connect(), maxdb_connect()

maxdb_insert_id

(PECL)

maxdb_insert_id

(no version information, might be only in CVS)

maxdb->insert_id -- Returns the auto generated id used in the last query

Description

Procedural style:

mixed maxdb_insert_id ( resource link )

Object oriented style (property):

class maxdb {

mixed insert_id

}

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.

Valori restituiti

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.

Nota: If the number is greater than maximal int value, maxdb_insert_id() will return a string.

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

The above examples would produce the following output:

New Record has id 1.

maxdb_kill

(PECL)

maxdb_kill

(no version information, might be only in CVS)

maxdb->kill -- Disconnects from a MaxDB server

Description

Procedural style:

bool maxdb_kill ( resource link, int processid )

Object oriented style (method)

class maxdb {

bool kill ( int processid )

}

This function is used to disconnect from a MaxDB server specified by the processid parameter.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

maxdb_thread_id()

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

The above examples would produce the following output:

Error: Session not connected

maxdb_master_query

(PECL)

maxdb_master_query -- Enforce execution of a query on the master in a master/slave setup

Description

bool maxdb_master_query ( resource link, string query )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

maxdb_more_results

(PECL)

maxdb_more_results

(no version information, might be only in CVS)

maxdb->more_results -- Check if there any more query results from a multi query

Description

bool maxdb_more_results ( resource link )

maxdb_more_results() indicates if one or more result sets are available from a previous call to maxdb_multi_query().

Return values

Always FALSE.

Example

See maxdb_multi_query().

maxdb_multi_query

(PECL)

maxdb_multi_query

(no version information, might be only in CVS)

maxdb->multi_query -- Performs a query on the database

Description

Procedural style:

bool maxdb_multi_query ( resource link, string query )

Object oriented style (method):

class maxdb {

bool multi_query ( string query )

}

The maxdb_multi_query() works like the function maxdb_query(). Multiple queries are not yet supported.

Return values

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

The above examples would produce the following output:

maxdb_next_result

(PECL)

maxdb_next_result

(no version information, might be only in CVS)

maxdb->next_result -- Prepare next result from multi_query

Description

bool maxdb_next_result ( resource link )

Since multiple queries are not yet supported, maxdb_next_result() returns always FALSE.

Return values

FALSE

maxdb_num_fields

(PECL)

maxdb_num_fields

(no version information, might be only in CVS)

result->field_count -- Get the number of fields in a result

Description

Procedural style:

int maxdb_num_fields ( resource result )

Object oriented style (property):

class result {

int field_count

}

maxdb_num_fields() returns the number of fields from specified result set.

Valori restituiti

The number of fields from a result set

Vedere anche:

maxdb_fetch_field()

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

The above examples would produce the following output:

Result set has 3 fields.

maxdb_num_rows

(PECL)

maxdb_num_rows -- Gets the number of rows in a result

Description

Procedural style:

int maxdb_num_rows ( resource result )

Object oriented style (property):

class maxdb {

int num_rows

}

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.

Valori restituiti

Returns number of rows in the result set.

Nota: If the number of rows is greater than maximal int value, the number will be returned as a string.

Vedere anche:

maxdb_affected_rows() maxdb_store_result() maxdb_use_result() maxdb_query()

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

The above examples would produce the following output:

Result set has 15 rows.

maxdb_options

(PECL)

maxdb_options

(no version information, might be only in CVS)

maxdb->options -- Set options

Description

Procedural style:

bool maxdb_options ( resource link, int option, mixed value )

Object oriented style (method)

class maxdb {

bool options ( int option, mixed value )

}

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://dev.mysql.com/doc/maxdb/ The parameter option can be one of the following values:

Tabella 1. Valid options

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.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

maxdb_init(), maxdb_real_connect()

Example

See maxdb_real_connect().

maxdb_param_count

(PECL)

maxdb_param_count -- Alias di maxdb_stmt_param_count()

Descrizione

This function is an alias of: maxdb_stmt_param_count().

This function alias is deprecated and only exists for backwards compatibility reasons. It is recommended to not use this function as one day it may be removed from PHP.

maxdb_ping

(PECL)

maxdb_ping

(no version information, might be only in CVS)

maxdb->ping -- Pings a server connection, or tries to reconnect if the connection has gone down

Description

Procedural style:

bool maxdb_ping ( resource link )

Object oriented style (method):

class maxdb {

bool ping ( void )

}

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.

Return values

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

The above examples would produce the following output:

Our connection is ok!

maxdb_prepare

(PECL)

maxdb_prepare

(no version information, might be only in CVS)

maxdb->prepare -- Prepare a SQL statement for execution

Description

Procedure style:

resource maxdb_prepare ( resource link, string query )

Object oriented style (method)

class stmt {

resource prepare ( string 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.

Nota: 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.

Nota: 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.

Valori restituiti

maxdb_prepare() returns a statement resource or FALSE if an error occured.

Vedere anche:

maxdb_stmt_execute(), maxdb_stmt_fetch(), maxdb_stmt_bind_param(), maxdb_stmt_bind_result(), maxdb_stmt_close()

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

The above examples would produce the following output:

Rosemont is in district IL

maxdb_query

(PECL)

maxdb_query

(no version information, might be only in CVS)

maxdb->query -- Performs a query on the database

Description

Procedural style:

mixed maxdb_query ( resource link, string query [, int resultmode] )

Object oriented style (method):

class maxdb {

mixed query ( string query )

}

The maxdb_query() function is used to simplify the act of performing a query against the database represented by the link parameter.

Return values

Restituisce TRUE in caso di successo, FALSE in caso di fallimento. For SELECT, SHOW, DESCRIBE or EXPLAIN maxdb_query() will return a result resource.

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

The above examples would produce the following output:

Table mycity successfully created.
Select returned 25 rows.

maxdb_real_connect

(PECL)

maxdb_real_connect

(no version information, might be only in CVS)

maxdb->real_connect -- Opens a connection to a MaxDB server

Description

Procedural style

bool maxdb_real_connect ( resource link [, string hostname [, string username [, string passwd [, string dbname [, int port [, string socket]]]]]] )

Object oriented style (method)

class maxdb {

bool real_connect ( [string hostname [, string username [, string passwd [, string dbname [, int port [, 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.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

maxdb_connect(), maxdb_init(), maxdb_options(), maxdb_ssl_set(), maxdb_close().

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

The above examples would produce the following output:

Connection: localhost <...>

maxdb_real_escape_string

(PECL)

maxdb_real_escape_string

(no version information, might be only in CVS)

maxdb->real_escape_string -- Escapes special characters in a string for use in a SQL statement, taking into account the current charset of the connection

Description

Procedural style:

string maxdb_real_escape_string ( resource link, string escapestr )

Object oriented style (method):

class maxdb {

string real_escape_sring ( string escapestr )

}

This function is used to create a legal SQL string that you can use in a 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 ', ".

Return values

Returns an escaped string.

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

The above examples would produce the following output:

Warning: maxdb_query(): -5016 POS(43) Missing delimiter: ) <...>
Error: 42000
1 Row inserted.

maxdb_real_query

(PECL)

maxdb_real_query

(no version information, might be only in CVS)

maxdb->real_query -- Execute an SQL query

Description

Procedural style

bool maxdb_real_query ( resource link, string query )

Object oriented style (method):

class maxdb {

bool real_query ( string query )

}

The maxdb_real_query() is functionally identical with the maxdb_query().

Nota: In order to determine if a given query should return a result set or not, see maxdb_field_count().

Return values

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

maxdb_report

(PECL)

maxdb_report -- Enables or disables internal report functions

Description

bool maxdb_report ( int flags )

Example

Esempio 1. Procedural style

<?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);
?>

The above examples would produce the following output:

Warning: maxdb_query(): -4004 POS(18) Unknown table name:NONEXISTINGTABLE <...>

maxdb_rollback

(PECL)

maxdb_rollback

(no version information, might be only in CVS)

maxdb->rollback -- Rolls back current transaction

Description

bool maxdb_rollback ( resource link )

class maxdb {

bool rollback ( void )

}

Rollbacks the current transaction for the database specified by the link parameter.

Return values

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

The above examples would produce the following output:

0 rows in table mycity.
25 rows in table mycity (after rollback).

maxdb_rpl_parse_enabled

(PECL)

maxdb_rpl_parse_enabled -- Check if RPL parse is enabled

Description

int maxdb_rpl_parse_enabled ( resource link )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

maxdb_rpl_probe

(PECL)

maxdb_rpl_probe -- RPL probe

Description

bool maxdb_rpl_probe ( resource link )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

maxdb_rpl_query_type

(PECL)

maxdb_rpl_query_type

(no version information, might be only in CVS)

maxdb->rpl_query_type -- Returns RPL query type

Description

int maxdb_rpl_query_type ( resource link )

Object oriented style (method)

class maxdb {

int rpl_query_type ( void )

}

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

maxdb_select_db

(PECL)

maxdb_select_db

(no version information, might be only in CVS)

maxdb->select_db -- Selects the default database for database queries

Description

bool maxdb_select_db ( resource 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.

Nota: 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().

Return values

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

The above examples would produce the following output:

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 [] <...>

maxdb_send_long_data

(PECL)

maxdb_send_long_data -- Alias di maxdb_stmt_send_long_data()

Descrizione

This function is an alias of: maxdb_stmt_send_long_data().

This function alias is deprecated and only exists for backwards compatibility reasons. It is recommended to not use this function as one day it may be removed from PHP.

maxdb_send_query

(PECL)

maxdb_send_query

(no version information, might be only in CVS)

maxdb->send_query -- Send the query and return

Description

bool maxdb_send_query ( resource link, string query )

Object oriented style (method)

This function is an alias of: maxdb_options().

maxdb_sqlstate

(PECL)

maxdb_sqlstate

(no version information, might be only in CVS)

maxdb->sqlstate -- Returns the SQLSTATE error from previous MaxDB operation

Description

Procedural style:

string maxdb_sqlstate ( resource link )

Object oriented style (property):

class maxdb {

string sqlstate

}

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.

Nota: Note that not all MaxDB errors are yet mapped to SQLSTATE's. The value HY000 (general error) is used for unmapped errors.

Return values

Returns a string containing the SQLSTATE error code for the last error. The error code consists of five characters. '00000' means no error.

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

The above examples would produce the following output:

Warning: maxdb_query(): -6000 POS(20) Duplicate table name:CITY [I6000] <...>
Error - SQLSTATE I6000.

maxdb_ssl_set

(PECL)

maxdb_ssl_set

(no version information, might be only in CVS)

maxdb->ssl_set -- Used for establishing secure connections using SSL

Description

Procedural style:

bool maxdb_ssl_set ( resource link, string key, string cert, string ca, string capath, string cipher )

Object oriented style (method):

class maxdb {

bool ssl_set ( string key, string cert, string ca, string capath, string cipher )

}

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

maxdb_stat

(PECL)

maxdb_stat

(no version information, might be only in CVS)

maxdb->stat -- Gets the current system status

Description

Procedural style:

string maxdb_stat ( resource link )

Object oriented style (method):

class maxdb {

string maxdb->stat ( void )

}

maxdb_stat() returns a string containing several information about the MaxDB server running.

Return values

A string describing the server status. FALSE if an error occurred.

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

The above examples would produce the following output:

System status: Kernel    7<...>

maxdb_stmt_affected_rows

(PECL)

maxdb_stmt_affected_rows

(no version information, might be only in CVS)

maxdb_stmt->affected_rows -- Returns the total number of rows changed, deleted, or inserted by the last executed statement

Description

Procedural style :

int maxdb_stmt_affected_rows ( resource stmt )

Object oriented style (property):

class stmt {

int affected_rows

}

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.

Return Values

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.

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

The above examples would produce the following output:

rows inserted: 4

maxdb_stmt_bind_param

(PECL)

maxdb_stmt_bind_param

(no version information, might be only in CVS)

stmt->bind_param -- Binds variables to a prepared statement as parameters

Description

Procedural style:

bool maxdb_stmt_bind_param ( resource stmt, string types, mixed &var1 [, mixed &...] )

Object oriented style (method):

class stmt {

bool bind_param ( array types, mixed &var1 [, mixed &...] )

}

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.

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 a 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().

Tabella 1. 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 send in packages

Return values

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

The above examples would produce the following output:

1 Row inserted.
1 Row deleted.

Esempio 3. Procedural style (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);
?>

The above examples would produce the following output:

21.600000

Esempio 4. Procedural style (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);
?>

The above examples would produce the following output:

maxdb_stmt_bind_result

(PECL)

maxdb_stmt_bind_result

(no version information, might be only in CVS)

stmt->bind_result -- Binds variables to a prepared statement for result storage

Description

Procedural style:

bool maxdb_stmt_bind_result ( resource stmt, mixed &var1 [, mixed &...] )

Object oriented style (method):

class stmt {

bool bind_result ( mixed &var1 [, mixed &...] )

}

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, ....

Nota: 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.

Return values

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Example

Esempio 1. Object oriented style

<?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();

?>

Esempio 2. Procedural style

<?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);
?>

The above examples would produce the following output:

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

maxdb_stmt_close_long_data

(PECL)

maxdb_stmt_close_long_data

(no version information, might be only in CVS)

stmt->close_long_data -- Ends a sequence of maxdb_stmt_send_long_data()

Description

Procedural style:

bool maxdb_stmt_close_long_data ( resource stmt, int param_nr )

Object oriented style (method):

class maxdb_stmt {

bool maxdb_stmt->close_long_data ( void )

}

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.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

maxdb_prepare(), maxdb_stmt_bind_param()

maxdb_stmt_close

(PECL)

maxdb_stmt_close

(no version information, might be only in CVS)

maxdb_stmt->close -- Closes a prepared statement

Description

Procedural style:

bool maxdb_stmt_close ( resource stmt )

Object oriented style (method):

class maxdb_stmt {

bool maxdb_stmt->close ( void )

}

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.

Return values

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

maxdb_stmt_data_seek

(PECL)

maxdb_stmt_data_seek

(no version information, might be only in CVS)

stmt->data_seek -- Seeks to an arbitray row in statement result set

Description

Procedural style:

bool maxdb_stmt_data_seek ( resource statement, int offset )

Object oriented style (method):

class stmt {

bool data_seek ( int 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).

Return values

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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. 400 */
   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);
?>

The above examples would produce the following output:

City: Dallas  Zip: 75243

maxdb_stmt_errno

(PECL)

maxdb_stmt_errno

(no version information, might be only in CVS)

maxdb_stmt->errno -- Returns the error code for the most recent statement call

Description

Procedural style :

int maxdb_stmt_errno ( resource stmt )

Object oriented style (property):

class stmt {

int errno

}

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.

Nota: For possible error codes see documentation of SQLDBC: http://dev.mysql.com/doc/maxdb/.

Return values

An error code value. Zero means no error occurred.

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

The above examples would produce the following output:

Warning: maxdb_stmt_execute(): -4004 POS(23) Unknown table name:MYCITY [42000] <...>
Error: -4004.

maxdb_stmt_error

(PECL)

maxdb_stmt_error

(no version information, might be only in CVS)

maxdb_stmt->error -- Returns a string description for last statement error

Description

Procedural style:

string maxdb_stmt_error ( resource stmt )

Object oriented style (property):

class stmt {

string error

}

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.

Return values

A string that describes the error. An empty string if no error occurred.

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

The above examples would produce the following output:

Warning: maxdb_stmt_execute(): -4004 POS(23) Unknown table name:MYCITY [42000] <...>
Error: POS(23) Unknown table name:MYCITY.

maxdb_stmt_execute

(PECL)

maxdb_stmt_execute

(no version information, might be only in CVS)

stmt->execute -- Executes a prepared Query

Description

Procedural style:

bool maxdb_stmt_execute ( resource stmt )

Object oriented style (method):

class stmt {

bool execute ( void )

}

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.

Nota: When using maxdb_stmt_execute(), the maxdb_fetch() function must be used to fetch the data prior to preforming any additional queries.

Return values

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Example

Esempio 1. Object oriented style

<?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(); 
?>

Esempio 2. Procedural style

<?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); 
?>

The above examples would produce the following output:

11111 (Georgetown,NY)
22222 (Hubbatown,CA)

maxdb_stmt_fetch

(PECL)

maxdb_stmt_fetch

(no version information, might be only in CVS)

stmt->fetch -- Fetch results from a prepared statement into the bound variables

Description

Procedural style:

bool maxdb_stmt_fetch ( resource stmt )

Object oriented style (method):

class stmt {

bool fetch ( void )

}

maxdb_stmt_fetch() returns row data using the variables bound by maxdb_stmt_bind_result().

Nota: Note that all columns must be bound by the application before calling maxdb_stmt_fetch().

Return values

Tabella 1. Return values

Value	Description
`TRUE`	Success. Data has been fetched
`FALSE`	Error occured
`NULL`	No more rows/data exists

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

The above examples would produce the following output:

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)

maxdb_stmt_free_result

(PECL)

maxdb_stmt_free_result

(no version information, might be only in CVS)

stmt->free_result -- Frees stored result memory for the given statement handle

Description

Procedural style:

void maxdb_stmt_free_result ( resource stmt )

Object oriented style (method):

class stmt {

void free_result ( void )

}

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().

Valori restituiti

This function doesn't return any value.

Vedere anche:

maxdb_stmt_store_result()

maxdb_stmt_init

(PECL)

maxdb_stmt_init

(no version information, might be only in CVS)

maxdb->stmt_init -- Initializes a statement and returns an resource for use with maxdb_stmt_prepare

Description

Procedural style :

resource maxdb_stmt_init ( resource link )

Object oriented style (property):

class maxdb {

object stmt_init ( void )

}

Allocates and initializes a statement resource suitable for maxdb_stmt_prepare().

Nota: Any subsequent calls to any maxdb_stmt function will fail until maxdb_stmt_prepare() was called.

Valori restituiti

Returns an resource.

Vedere anche:

maxdb_stmt_prepare()

maxdb_stmt_num_rows

(PECL)

maxdb_stmt_num_rows

(no version information, might be only in CVS)

stmt->num_rows -- Return the number of rows in statements result set

Description

Procedural style :

int maxdb_stmt_num_rows ( resource stmt )

Object oriented style (property):

class stmt {

int num_rows

}

Returns the number of rows in the result set.

Return values

An integer representing the number of rows in result set.

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

The above examples would produce the following output:

Number of rows: 25.

maxdb_stmt_param_count

(PECL)

maxdb_stmt_param_count

(no version information, might be only in CVS)

stmt->param_count -- Returns the number of parameter for the given statement

Description

Procedural style:

int maxdb_stmt_param_count ( resource stmt )

Object oriented style (property):

class stmt {

int param_count

}

maxdb_stmt_param_count() returns the number of parameter markers present in the prepared statement.

Valori restituiti

returns an integer representing the number of parameters.

Vedere anche:

maxdb_prepare()

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

The above examples would produce the following output:

Statement has 2 markers.

maxdb_stmt_prepare

(PECL)

maxdb_stmt_prepare

(no version information, might be only in CVS)

stmt->prepare -- Prepare a SQL statement for execution

Description

Procedure style:

bool maxdb_stmt_prepare ( resource stmt, string query )

Object oriented style (method)

class stmt {

mixed prepare ( string query )

}

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.

Nota: 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.

Nota: 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.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

maxdb_stmt_init(), maxdb_stmt_execute(), maxdb_stmt_fetch(), maxdb_stmt_bind_param(), maxdb_stmt_bind_result(), maxdb_stmt_close()

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

The above examples would produce the following output:

Portland is in district OR

maxdb_stmt_reset

(PECL)

maxdb_stmt_reset

(no version information, might be only in CVS)

stmt->reset -- Resets a prepared statement

Description

Procedural style:

bool maxdb_stmt_reset ( resource stmt )

Object oriented style (method):

class stmt {

bool reset ( void )

}

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

maxdb_stmt_result_metadata

(PECL)

maxdb_stmt_result_metadata -- Returns result set metadata from a prepared statement

Description

Procedural style:

resource maxdb_stmt_result_metadata ( resource stmt )

Object oriented style (method):

class stmt {

resource result_metadata ( void )

}

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.

Nota: This result set pointer can be passed as an argument to any of the field-based functions that process result set metadata, such as:
maxdb_num_fields()
maxdb_fetch_field()
maxdb_fetch_field_direct()
maxdb_fetch_fields()
maxdb_field_count()
maxdb_field_seek()
maxdb_field_tell()
maxdb_free_result()

The result set structure should be freed when you are done with it, which you can do by passing it to maxdb_free_result()

Nota: 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().

Valori restituiti

maxdb_stmt_result_metadata() returns a result resource or FALSE if an error occured.

Example

Esempio 1. Object oriented style
<?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(); ?>

Esempio 2. Procedural style
<?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); ?>

The above examples would produce the following output:

Fieldname: ID

maxdb_stmt_send_long_data

(PECL)

maxdb_stmt_send_long_data

(no version information, might be only in CVS)

stmt->send_long_data -- Send data in blocks

Description

Procedural style:

bool maxdb_stmt_send_long_data ( resource stmt, int param_nr, string data )

Object oriented style (method)

class stmt {

bool stmt_send_long_data ( int 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.

Nota: 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().

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

maxdb_prepare(), maxdb_stmt_bind_param()

maxdb_stmt_sqlstate

(PECL)

maxdb_stmt_sqlstate -- Returns SQLSTATE error from previous statement operation

Description

string maxdb_stmt_sqlstate ( resource 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.

Nota: Note that not all MaxDB errors are yet mapped to SQLSTATE's. The value HY000 (general error) is used for unmapped errors.

Return values

Returns a string containing the SQLSTATE error code for the last error. The error code consists of five characters. '00000' means no error.

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

The above examples would produce the following output:

Warning: maxdb_stmt_execute(): -4004 POS(23) Unknown table name:MYCITY [42000] <...>
Error: 42000.

maxdb_stmt_store_result

(PECL)

maxdb_stmt_store_result

(no version information, might be only in CVS)

maxdb->store_result -- Transfers a result set from a prepared statement

Description

Procedural style:

bool maxdb_stmt_store_result ( resource stmt )

Object oriented style (method):

class maxdb {

object store_result ( void )

}

maxdb_stmt_store_result() has no functionally effect and should not be used for retrieving data from MaxDB server.

Return values

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

The above examples would produce the following output:

Number of rows: 25.

maxdb_store_result

(PECL)

maxdb_store_result

(no version information, might be only in CVS)

maxdb->store_result -- Transfers a result set from the last query

Description

Procedural style:

resource maxdb_store_result ( resource link )

Object oriented style (method):

class maxdb {

object store_result ( void )

}

This function has no functionally effect.

Return values

Returns a result resource or FALSE if an error occurred.

Example

See maxdb_multi_query().

maxdb_thread_id

(PECL)

maxdb_thread_id

(no version information, might be only in CVS)

maxdb->thread_id -- Returns the thread ID for the current connection

Description

Procedural style:

int maxdb_thread_id ( resource link )

Object oriented style (property):

class maxdb {

int thread_id

}

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.

Nota: 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.

Return values

maxdb_thread_id() returns the Thread ID for the current connection.

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

The above examples would produce the following output:

Warning: maxdb_query(): -10821 Session not connected <...>
Error: Session not connected

maxdb_thread_safe

(no version information, might be only in CVS)

maxdb_thread_safe -- Returns whether thread safety is given or not

Description

Procedural style:

bool maxdb_thread_safe ( void )

maxdb_thread_safe() indicates whether the client library is compiled as thread-safe.

Return values

TRUE if the client library is thread-safe, otherwise FALSE.

maxdb_use_result

(PECL)

maxdb_use_result

(no version information, might be only in CVS)

maxdb->use_result -- Initiate a result set retrieval

Description

Procedural style:

resource maxdb_use_result ( resource link )

Object oriented style (method):

class maxdb {

resource use_result ( void )

}

maxdb_use_result() has no effect.

Return values

Returns result or FALSE in case of error.

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

The above examples would produce the following output:

maxdb_warning_count

(PECL)

maxdb_warning_count

(no version information, might be only in CVS)

maxdb->warning_count -- Returns the number of warnings from the last query for the given link

Description

Procedural style:

int maxdb_warning_count ( resource link )

Object oriented style (property):

class maxdb {

int warning_count

}

maxdb_warning_count() returns the number of warnings from the last query in the connection represented by the link parameter.

Return values

Number of warnings or zero if there are no warnings.

Example

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

The above examples would produce the following output:

Warning: maxdb_query(): -8004 POS(62) Constant must be compatible with column type and length <...>
Number of warning: 0

LXXI. MCAL Functions

Introduzione

MCAL stands for Modular Calendar Access Library.

Libmcal is a C library for accessing calendars. It's written to be very modular, with pluggable drivers. MCAL is the calendar equivalent of the IMAP module for mailboxes.

With mcal support, a calendar stream can be opened much like the mailbox stream with the IMAP support. Calendars can be local file stores, remote ICAP servers, or other formats that are supported by the mcal library.

Calendar events can be pulled up, queried, and stored. There is also support for calendar triggers (alarms) and recurring events.

With libmcal, central calendar servers can be accessed, removing the need for any specific database or local file programming.

Most of the functions use an internal event structure that is unique for each stream. This alleviates the need to pass around large objects between functions. There are convenience functions for setting, initializing, and retrieving the event structure values.

Nota: Questo modulo è stato spostato nel repository PECL e non sarà più rilascio con il PHP dalla versione 5.0.0.

Nota: PHP had an ICAP extension previously, but the original library and the PHP extension is not supported anymore. The suggested replacement is MCAL.

Nota: Questo modulo non è disponibile su piattaforme Windows.

Requisiti

This extension requires the mcal library to be installed. Grab the latest version from http://mcal.chek.com/ and compile and install it.

Installazione

After you installed the mcal library, to get these functions to work, you have to compile PHP -with-mcal[=DIR].

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

MCAL_SUNDAY (integer)
MCAL_MONDAY (integer)
MCAL_TUESDAY (integer)
MCAL_WEDNESDAY (integer)
MCAL_THURSDAY (integer)
MCAL_FRIDAY (integer)
MCAL_SATURDAY (integer)
MCAL_JANUARY (integer)
MCAL_FEBRUARY (integer)
MCAL_MARCH (integer)
MCAL_APRIL (integer)
MCAL_MAY (integer)
MCAL_JUNE (integer)
MCAL_JULY (integer)
MCAL_AUGUST (integer)
MCAL_SEPTEMBER (integer)
MCAL_OCTOBER (integer)
MCAL_NOVEMBER (integer)
MCAL_DECEMBER (integer)
MCAL_RECUR_NONE (integer)
MCAL_RECUR_DAILY (integer)
MCAL_RECUR_WEEKLY (integer)
MCAL_RECUR_MONTHLY_MDAY (integer)
MCAL_RECUR_MONTHLY_WDAY (integer)
MCAL_RECUR_YEARLY (integer)
MCAL_M_SUNDAY (integer)
MCAL_M_MONDAY (integer)
MCAL_M_TUESDAY (integer)
MCAL_M_WEDNESDAY (integer)
MCAL_M_THURSDAY (integer)
MCAL_M_FRIDAY (integer)
MCAL_M_SATURDAY (integer)
MCAL_M_WEEKDAYS (integer)
MCAL_M_WEEKEND (integer)
MCAL_M_ALLDAYS (integer)

Sommario
mcal_append_event -- Store a new event into an MCAL calendar
mcal_close -- Close an MCAL stream
mcal_create_calendar -- Create a new MCAL calendar
mcal_date_compare -- Compares two dates
mcal_date_valid -- Returns TRUE if the given year, month, day is a valid date
mcal_day_of_week -- Returns the day of the week of the given date
mcal_day_of_year -- Returns the day of the year of the given date
mcal_days_in_month -- Returns the number of days in a month
mcal_delete_calendar -- Delete an MCAL calendar
mcal_delete_event -- Delete an event from an MCAL calendar
mcal_event_add_attribute -- Adds an attribute and a value to the streams global event structure
mcal_event_init -- Initializes a streams global event structure
mcal_event_set_alarm -- Sets the alarm of the streams global event structure
mcal_event_set_category -- Sets the category of the streams global event structure
mcal_event_set_class -- Sets the class of the streams global event structure
mcal_event_set_description -- Sets the description of the streams global event structure
mcal_event_set_end -- Sets the end date and time of the streams global event structure
mcal_event_set_recur_daily -- Sets the recurrence of the streams global event structure
mcal_event_set_recur_monthly_mday -- Sets the recurrence of the streams global event structure
mcal_event_set_recur_monthly_wday -- Sets the recurrence of the streams global event structure
mcal_event_set_recur_none -- Sets the recurrence of the streams global event structure
mcal_event_set_recur_weekly -- Sets the recurrence of the streams global event structure
mcal_event_set_recur_yearly -- Sets the recurrence of the streams global event structure
mcal_event_set_start -- Sets the start date and time of the streams global event structure
mcal_event_set_title -- Sets the title of the streams global event structure
mcal_expunge -- Deletes all events marked for being expunged
mcal_fetch_current_stream_event -- Returns an object containing the current streams event structure
mcal_fetch_event -- Fetches an event from the calendar stream
mcal_is_leap_year -- Returns if the given year is a leap year or not
mcal_list_alarms -- Return a list of events that has an alarm triggered at the given datetime
mcal_list_events -- Return a list of IDs for a date or a range of dates
mcal_next_recurrence -- Returns the next recurrence of the event
mcal_open -- Opens up an MCAL connection
mcal_popen -- Opens up a persistent MCAL connection
mcal_rename_calendar -- Rename an MCAL calendar
mcal_reopen -- Reopens an MCAL connection
mcal_snooze -- Turn off an alarm for an event
mcal_store_event -- Modify an existing event in an MCAL calendar
mcal_time_valid -- Returns TRUE if the given hour, minutes and seconds is a valid time
mcal_week_of_year -- Returns the week number of the given date

mcal_append_event

(PHP 4, PECL)

mcal_append_event -- Store a new event into an MCAL calendar

Description

mcal_fetch_current_stream_event

(PHP 3 >= 3.0.13, PHP 4, PECL)

mcal_fetch_current_stream_event -- Returns an object containing the current streams event structure

Description

object mcal_fetch_current_stream_event ( int stream )

mcal_fetch_current_stream_event() returns the current stream's event structure as an object containing:

int id - ID of that event.
int public - TRUE if the event if public, FALSE if it is private.
string category - Category string of the event.
string title - Title string of the event.
string description - Description string of the event.
int alarm - number of minutes before the event to send an alarm/reminder.
object start - Object containing a datetime entry.
object end - Object containing a datetime entry.
int recur_type - recurrence type
int recur_interval - recurrence interval
datetime recur_enddate - recurrence end date
int recur_data - recurrence data

All datetime entries consist of an object that contains:

int year - year
int month - month
int mday - day of month
int hour - hour
int min - minutes
int sec - seconds
int alarm - minutes before event to send an alarm

mcal_fetch_event

(PHP 3 >= 3.0.13, PHP 4, PECL)

mcal_fetch_event -- Fetches an event from the calendar stream

Description

object mcal_fetch_event ( int mcal_stream, int event_id [, int options] )

mcal_fetch_event() fetches an event from the calendar stream specified by id.

Returns an event object consisting of:

int id - ID of that event.
int public - TRUE if the event if public, FALSE if it is private.
string category - Category string of the event.
string title - Title string of the event.
string description - Description string of the event.
int alarm - number of minutes before the event to send an alarm/reminder.
object start - Object containing a datetime entry.
object end - Object containing a datetime entry.
int recur_type - recurrence type
int recur_interval - recurrence interval
datetime recur_enddate - recurrence end date
int recur_data - recurrence data

All datetime entries consist of an object that contains:

int year - year
int month - month
int mday - day of month
int hour - hour
int min - minutes
int sec - seconds
int alarm - minutes before event to send an alarm

The possible values for recur_type are:

0 - Indicates that this event does not recur
1 - This event recurs daily
2 - This event recurs on a weekly basis
3 - This event recurs monthly on a specific day of the month (e.g. the 10th of the month)
4 - This event recurs monthly on a sequenced day of the week (e.g. the 3rd Saturday)
5 - This event recurs on an annual basis

mcal_is_leap_year

(PHP 3 >= 3.0.13, PHP 4, PECL)

mcal_is_leap_year -- Returns if the given year is a leap year or not

mcal_week_of_year

(PHP 4, PECL)

mcal_week_of_year -- Returns the week number of the given date

Description

int mcal_week_of_year ( int day, int month, int year )

mcal_week_of_year() returns the week number of the given date.

LXXII. Mcrypt Encryption Functions

Introduzione

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".

Requisiti

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. Windows users will find all the needed compiled mcrypt binaries at http://ftp.emini.dk/pub/php/win32/mcrypt/.

As of PHP 5.0.0 you will need libmcrypt Version 2.5.6 or greater.

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.

Installazione

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.

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

Tabella 1. Mcrypt configuration options

Name	Default	Changeable	Changelog
mcrypt.algorithms_dir	NULL	PHP_INI_ALL	Available since PHP 4.0.2.
mcrypt.modes_dir	NULL	PHP_INI_ALL	Available since PHP 4.0.2.

Per maggiori dettagli sulle costanti PHP_INI_* vedere Appendice G.

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

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_STREAM is an extra mode to include some stream algorithms like WAKE or RC4.

Some other mode and random device constants:

MCRYPT_ENCRYPT (integer)
MCRYPT_DECRYPT (integer)
MCRYPT_DEV_RANDOM (integer)
MCRYPT_DEV_URANDOM (integer)
MCRYPT_RAND (integer)

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).

Esempi

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.
Esempio 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); ?>
This example will give you the encrypted data as a string in $encrypted_data.

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.
Esempio 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); ?>
This example will give you the encrypted data as a string in $encrypted_data. For a full example see mcrypt_module_open().

Sommario
mcrypt_cbc -- Encrypt/decrypt data in CBC mode
mcrypt_cfb -- Encrypt/decrypt data in CFB mode
mcrypt_create_iv -- Create an initialization vector (IV) from a random source
mcrypt_decrypt -- Decrypts crypttext with given parameters
mcrypt_ecb -- Deprecated: Encrypt/decrypt 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 -- This function 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 -- Get the block size of the specified cipher
mcrypt_get_cipher_name -- Get 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 -- Get the key size of the specified cipher
mcrypt_list_algorithms -- Get an array of all supported ciphers
mcrypt_list_modes -- Get an array of all supported modes
mcrypt_module_close -- Close 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 -- Encrypt/decrypt data in OFB mode
mdecrypt_generic -- Decrypt data

The source can be MCRYPT_RAND (system random number generator), MCRYPT_DEV_RANDOM (read data from /dev/random) and MCRYPT_DEV_URANDOM (read data from /dev/urandom). MCRYPT_RAND is the only one supported on Windows because Windows (of course) doesn't have /dev/random or /dev/urandom.

Nota: When using MCRYPT_RAND, remember to call srand() before mcrypt_create_iv() to initialize the random number generator; it is not seeded automatically like rand() is.

Esempio 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); ?>

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.

More information can be found at http://www.ciphersbyritter.com/GLOSSARY.HTM#IV, http://fn2.freenet.edmonton.ab.ca/~jsavard/crypto/co0409.htm and in chapter 9.3 of Applied Cryptography by Schneier (ISBN 0-471-11709-9) for a discussion of this topic.

mcrypt_decrypt

(PHP 4 >= 4.0.2, PHP 5)

mcrypt_decrypt -- Decrypts crypttext with given parameters

Description

string mcrypt_decrypt ( string cipher, string key, string data, string mode [, string iv] )

mcrypt_decrypt() decrypts the data and returns the unencrypted data.

Cipher is one of the MCRYPT_ciphername constants of the name of the algorithm as string.

Key is the key with which the data is encrypted. If it's smaller that the required keysize, it is padded with '\0'.

string mcrypt_enc_get_modes_name ( resource td )

This function returns the name of the mode.

Esempio 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"; ?>
Prints:
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

Description

array mcrypt_enc_get_supported_key_sizes ( resource td )

string mcrypt_encrypt ( string cipher, string key, string data, string mode [, string iv] )

mcrypt_encrypt() encrypts the data and returns the encrypted data.

Cipher is one of the MCRYPT_ciphername constants of the name of the algorithm as string.

Key is the key with which the data will be encrypted. If it's smaller that 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 is the data that will be encrypted with the given cipher and mode. If the size of the data is not n * blocksize, the data will be padded with '\0'. The returned crypttext can be larger that the size of the data that is given by data.

Mode is one of the MCRYPT_MODE_modename constants of one of "ecb", "cbc", "cfb", "ofb", "nofb" or "stream".

Esempio 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"; ?>
Il precedente esempio visualizzerà:
42 64

See also mcrypt_module_open() for a more advanced API and an example.

mcrypt_generic_deinit

(PHP 4 >= 4.1.1, PHP 5)

mcrypt_generic_deinit -- This function deinitializes an encryption module

Description

bool mcrypt_generic_deinit ( resource 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.) Returns FALSE on error, or TRUE on success.

See for an example mcrypt_module_open() and the entry on mcrypt_generic_init().

mcrypt_generic_end

(PHP 4 >= 4.0.2, PHP 5)

mcrypt_generic_end -- This function terminates encryption

string mcrypt_get_cipher_name ( int cipher )

string mcrypt_get_cipher_name ( string 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.

Esempio 1. mcrypt_get_cipher_name() Example
<?php $cipher = MCRYPT_TripleDES; echo mcrypt_get_cipher_name($cipher); ?>
Il precedente esempio visualizzerà:
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

Description

int mcrypt_get_iv_size ( string cipher, string mode )

mcrypt_get_iv_size() returns the size of the Initialisation Vector (IV) in bytes. On error the function returns FALSE. If the IV is ignored in the specified cipher/mode combination zero is returned.

cipher is one of the MCRYPT_ciphername constants of the name of the algorithm as string.

mode is one of the MCRYPT_MODE_modename constants or one of "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.

It is more useful to use the mcrypt_enc_get_iv_size() function as this uses the resource returned by mcrypt_module_open().

Esempio 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"; ?>

mcrypt_get_key_size

(PHP 3 >= 3.0.8, PHP 4, PHP 5)

mcrypt_get_key_size -- Get the key size of the specified cipher

Description

int mcrypt_get_key_size ( int cipher )

int mcrypt_get_key_size ( string cipher, string module )

bool mcrypt_module_close ( resource td )

array mcrypt_module_get_supported_key_sizes ( string algorithm [, string lib_dir] )

resource mcrypt_module_open ( string 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(). Normally it returns an encryption descriptor, or FALSE on error.

The algorithm_directory and mode_directory are used to locate the encryption modules. When you supply a directory name, it is used. When you set one of these to the empty string (""), the value set by the mcrypt.algorithms_dir or mcrypt.modes_dir ini-directive is used. When these are not set, the default directories that are used are the ones that were compiled in into libmcrypt (usually /usr/local/lib/libmcrypt).

Esempio 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.

Esempio 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, used 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"; ?>

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

Description

bool mcrypt_module_self_test ( string algorithm [, string lib_dir] )

This function runs the self test on the algorithm specified. The optional lib_dir parameter can contain the location of where the algorithm module is on the system.

The function returns TRUE if the self test succeeds, or FALSE when if fails.

Esempio 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)); ?>
Il precedente esempio visualizzerà:
bool(true) bool(false)

mcrypt_ofb

(PHP 3 >= 3.0.8, PHP 4, PHP 5)

mcrypt_ofb -- Encrypt/decrypt data in OFB mode

Description

string mcrypt_ofb ( int cipher, string key, string data, int mode, string iv )

string mcrypt_ofb ( string 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 -- Decrypt data

Description

string mdecrypt_generic ( resource td, string data )

This function decrypts data. Note that the length of the returned string can in fact be longer then the unencrypted string, due to the padding of the data.

Esempio 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 above example 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.

LXXIII. MCVE Payment Functions

Introduzione

These functions interface the MCVE API (libmcve), allowing you to work directly with MCVE from your PHP scripts. MCVE is Main Street Softworks' solution to direct credit card processing for Linux / Unix ( 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 module for PHP, you can process credit cards directly through MCVE via your PHP scripts. The following references will outline the process.

Nota: MCVE is the replacement for RedHat's CCVS. They contracted with RedHat in late 2001 to migrate all existing clientele to the MCVE platform.

Nota: Questo modulo è stato spostato nel repository PECL e non sarà più rilascio con il PHP dalla versione 5.1.0.

Nota: Questo modulo non è disponibile su piattaforme Windows.

Installazione

To enable MCVE Support in PHP, first verify your LibMCVE installation directory. You will then need to configure PHP with the --with-mcve option. If you use this option without specifying the path to your MCVE installation, PHP will attempt to look in the default LibMCVE Install location (/usr/local). If MCVE is in a non-standard location, run configure with: --with-mcve=$mcve_path, where $mcve_path is the path to your MCVE installation. Please note that MCVE support requires that $mcve_path/lib and $mcve_path/include exist, and include mcve.h under the include directory and libmcve.so and/or libmcve.a under the lib directory.

Since MCVE has true server/client separation, there are no additional requirements for running PHP with MCVE support. To test your MCVE extension in PHP, you may connect to testbox.mcve.com on port 8333 for IP, or port 8444 for SSL using the MCVE PHP API. Use 'vitale' for your username, and 'test' for your password. Additional information about test facilities are available at http://www.mainstreetsoftworks.com/.

Vedere anche:

Additional documentation about MCVE's PHP API can be found at http://www.mainstreetsoftworks.com/docs/phpapi.pdf. Main Street's documentation is complete and should be the primary reference for functions.

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

MC_TRANTYPE (integer)
MC_USERNAME (integer)
MC_PASSWORD (integer)
MC_ACCOUNT (integer)
MC_TRACKDATA (integer)
MC_EXPDATE (integer)
MC_STREET (integer)
MC_ZIP (integer)
MC_CV (integer)
MC_COMMENTS (integer)
MC_CLERKID (integer)
MC_STATIONID (integer)
MC_APPRCODE (integer)
MC_AMOUNT (integer)
MC_PTRANNUM (integer)
MC_TTID (integer)
MC_USER (integer)
MC_PWD (integer)
MC_ACCT (integer)
MC_BDATE (integer)
MC_EDATE (integer)
MC_BATCH (integer)
MC_FILE (integer)
MC_ADMIN (integer)
MC_AUDITTYPE (integer)
MC_CUSTOM (integer)
MC_EXAMOUNT (integer)
MC_EXCHARGES (integer)
MC_RATE (integer)
MC_RENTERNAME (integer)
MC_RETURNCITY (integer)
MC_RETURNSTATE (integer)
MC_RETURNLOCATION (integer)
MC_PRIORITY (integer)
MC_INQUIRY (integer)
MC_CARDTYPES (integer)
MC_SUB (integer)
MC_MARKER (integer)
MC_DEVICETYPE (integer)
MC_ERRORCODE (integer)
MC_NEWBATCH (integer)
MC_CURR (integer)
MC_DESCMERCH (integer)
MC_DESCLOC (integer)
MC_ORIGTYPE (integer)
MC_PIN (integer)
MC_VOIDORIGTYPE (integer)
MC_TIMESTAMP (integer)
MC_PRIO_HIGH (integer)
MC_PRIO_NORMAL (integer)
MC_PRIO_LOW (integer)
MC_USER_PROC (integer)
MC_USER_USER (integer)
MC_USER_PWD (integer)
MC_USER_INDCODE (integer)
MC_USER_MERCHID (integer)
MC_USER_BANKID (integer)
MC_USER_TERMID (integer)
MC_USER_CLIENTNUM (integer)
MC_USER_STOREID (integer)
MC_USER_AGENTID (integer)
MC_USER_CHAINID (integer)
MC_USER_ZIPCODE (integer)
MC_USER_TIMEZONE (integer)
MC_USER_MERCHCAT (integer)
MC_USER_MERNAME (integer)
MC_USER_MERCHLOC (integer)
MC_USER_STATECODE (integer)
MC_USER_PHONE (integer)
MC_USER_SUB (integer)
MC_USER_CARDTYPES (integer)
MC_USER_MODE (integer)
MC_USER_VNUMBER (integer)
MC_USER_ROUTINGID (integer)
MC_USER_PPROPERTY (integer)
MC_USER_PID (integer)
MC_USER_PIDPWD (integer)
MC_USER_SMID (integer)
MC_USER_SMIDPWD (integer)
MC_USER_USDDIV (integer)
MC_USER_AUDDIV (integer)
MC_USER_DKKDIV (integer)
MC_USER_GBPDIV (integer)
MC_USER_HKDDIV (integer)
MC_USER_JPYDIV (integer)
MC_USER_NZDDIV (integer)
MC_USER_NOKDIV (integer)
MC_USER_SGDDIV (integer)
MC_USER_ZARDIV (integer)
MC_USER_SEKDIV (integer)
MC_USER_CHFDIV (integer)
MC_USER_CADDIV (integer)
MC_USER_DIVNUM (integer)
MC_CARD_VISA (integer)
MC_CARD_MC (integer)
MC_CARD_AMEX (integer)
MC_CARD_DISC (integer)
MC_CARD_JCB (integer)
MC_CARD_CB (integer)
MC_CARD_DC (integer)
MC_CARD_GIFT (integer)
MC_CARD_OTHER (integer)
MC_CARD_ALL (integer)
MC_MODE_AUTH (integer)
MC_MODE_SETTLE (integer)
MC_MODE_BOTH (integer)
MC_MODE_ALL (integer)
MC_EXCHARGES_REST (integer)
MC_EXCHARGES_GIFT (integer)
MC_EXCHARGES_MINI (integer)
MC_EXCHARGES_TELE (integer)
MC_EXCHARGES_OTHER (integer)
MC_EXCHARGES_LAUND (integer)
MC_EXCHARGES_NONE (integer)
MC_EXCHARGES_GAS (integer)
MC_EXCHARGES_MILE (integer)
MC_EXCHARGES_LATE (integer)
MC_EXCHARGES_1WAY (integer)
MC_EXCHARGES_VIOL (integer)
MC_TRAN_SALE (integer)
MC_TRAN_REDEMPTION (integer)
MC_TRAN_PREAUTH (integer)
MC_TRAN_VOID (integer)
MC_TRAN_PREAUTHCOMPLETE (integer)
MC_TRAN_FORCE (integer)
MC_TRAN_OVERRIDE (integer)
MC_TRAN_RETURN (integer)
MC_TRAN_RELOAD (integer)
MC_TRAN_CREDIT (integer)
MC_TRAN_SETTLE (integer)
MC_TRAN_INCREMENTAL (integer)
MC_TRAN_REVERSAL (integer)
MC_TRAN_ACTIVATE (integer)
MC_TRAN_BALANCEINQ (integer)
MC_TRAN_CASHOUT (integer)
MC_TRAN_TOREVERSAL (integer)
MC_TRAN_SETTLERFR (integer)
MC_TRAN_ISSUE (integer)
MC_TRAN_TIP (integer)
MC_TRAN_MERCHRETURN (integer)
MC_TRAN_IVRREQ (integer)
MC_TRAN_IVRRESP (integer)
MC_TRAN_ADMIN (integer)
MC_TRAN_PING (integer)
MC_TRAN_CHKPWD (integer)
MC_TRAN_CHNGPWD (integer)
MC_TRAN_LISTSTATS (integer)
MC_TRAN_LISTUSERS (integer)
MC_TRAN_GETUSERINFO (integer)
MC_TRAN_ADDUSER (integer)
MC_TRAN_EDITUSER (integer)
MC_TRAN_DELUSER (integer)
MC_TRAN_ENABLEUSER (integer)
MC_TRAN_DISABLEUSER (integer)
MC_TRAN_IMPORT (integer)
MC_TRAN_EXPORT (integer)
MC_TRAN_ERRORLOG (integer)
MC_TRAN_CLEARERRORLOG (integer)
MC_TRAN_GETSUBACCTS (integer)
MC_ADMIN_GUT (integer)
MC_ADMIN_GL (integer)
MC_ADMIN_GFT (integer)
MC_ADMIN_BT (integer)
MC_ADMIN_UB (integer)
MC_ADMIN_QC (integer)
MC_ADMIN_RS (integer)
MC_ADMIN_CTH (integer)
MC_ADMIN_CFH (integer)
MC_ADMIN_FORCESETTLE (integer)
MC_ADMIN_SETBATCHNUM (integer)
MC_ADMIN_RENUMBERBATCH (integer)
MC_ADMIN_FIELDEDIT (integer)
MC_ADMIN_CLOSEBATCH (integer)
MCVE_UNUSED (integer)
MCVE_NEW (integer)
MCVE_PENDING (integer)
MCVE_DONE (integer)
MCVE_GOOD (integer)
MCVE_BAD (integer)
MCVE_STREET (integer)
MCVE_ZIP (integer)
MCVE_UNKNOWN (integer)
MCVE_ERROR (integer)
MCVE_FAIL (integer)
MCVE_SUCCESS (integer)
MCVE_AUTH (integer)
MCVE_DENY (integer)
MCVE_CALL (integer)
MCVE_DUPL (integer)
MCVE_PKUP (integer)
MCVE_RETRY (integer)
MCVE_SETUP (integer)
MCVE_TIMEOUT (integer)
MCVE_SALE (integer)
MCVE_PREAUTH (integer)
MCVE_FORCE (integer)
MCVE_OVERRIDE (integer)
MCVE_RETURN (integer)
MCVE_SETTLE (integer)
MCVE_PROC (integer)
MCVE_USER (integer)
MCVE_PWD (integer)
MCVE_INDCODE (integer)
MCVE_MERCHID (integer)
MCVE_BANKID (integer)
MCVE_TERMID (integer)
MCVE_CLIENTNUM (integer)
MCVE_STOREID (integer)
MCVE_AGENTID (integer)
MCVE_CHAINID (integer)
MCVE_ZIPCODE (integer)
MCVE_TIMEZONE (integer)
MCVE_MERCHCAT (integer)
MCVE_MERNAME (integer)
MCVE_MERCHLOC (integer)
MCVE_STATECODE (integer)
MCVE_SERVICEPHONE (integer)

Sommario
mcve_adduser -- Add an MCVE user using usersetup structure
mcve_adduserarg -- Add a value to user configuration structure
mcve_bt -- Get unsettled batch totals
mcve_checkstatus -- Check to see if a transaction has completed
mcve_chkpwd -- Verify Password
mcve_chngpwd -- Change the system administrator's password
mcve_completeauthorizations -- Number of complete authorizations in queue, returning an array of their identifiers
mcve_connect -- Establish the connection to MCVE
mcve_connectionerror -- Get a textual representation of why a connection failed
mcve_deleteresponse -- Delete specified transaction from MCVE_CONN structure
mcve_deletetrans -- Delete specified transaction from MCVE_CONN structure
mcve_deleteusersetup -- Deallocate data associated with usersetup structure
mcve_deluser -- Delete an MCVE user account
mcve_destroyconn -- Destroy the connection and MCVE_CONN structure
mcve_destroyengine -- Free memory associated with IP/SSL connectivity
mcve_disableuser -- Disable an active MCVE user account
mcve_edituser -- Edit MCVE user using usersetup structure
mcve_enableuser -- Enable an inactive MCVE user account
mcve_force -- Send a FORCE to MCVE (typically, a phone-authorization)
mcve_getcell -- Get a specific cell from a comma delimited response by column name
mcve_getcellbynum -- Get a specific cell from a comma delimited response by column number
mcve_getcommadelimited -- Get the RAW comma delimited data returned from MCVE
mcve_getheader -- Get the name of the column in a comma-delimited response
mcve_getuserarg -- Grab a value from usersetup structure
mcve_getuserparam -- Get a user response parameter
mcve_gft -- Audit MCVE for Failed transactions
mcve_gl -- Audit MCVE for settled transactions
mcve_gut -- Audit MCVE for Unsettled Transactions
mcve_initconn -- Create and initialize an MCVE_CONN structure
mcve_initengine -- Ready the client for IP/SSL Communication
mcve_initusersetup -- Initialize structure to store user data
mcve_iscommadelimited -- Checks to see if response is comma delimited
mcve_liststats -- List statistics for all users on MCVE system
mcve_listusers -- List all users on MCVE system
mcve_maxconntimeout -- The maximum amount of time the API will attempt a connection to MCVE
mcve_monitor -- Perform communication with MCVE (send/receive data) Non-blocking
mcve_numcolumns -- Number of columns returned in a comma delimited response
mcve_numrows -- Number of rows returned in a comma delimited response
mcve_override -- Send an OVERRIDE to MCVE
mcve_parsecommadelimited -- Parse the comma delimited response so mcve_getcell, etc will work
mcve_ping -- Send a ping request to MCVE
mcve_preauth -- Send a PREAUTHORIZATION to MCVE
mcve_preauthcompletion -- Complete a PREAUTHORIZATION, ready it for settlement
mcve_qc -- Audit MCVE for a list of transactions in the outgoing queue
mcve_responseparam -- Get a custom response parameter
mcve_return -- Issue a RETURN or CREDIT to MCVE
mcve_returncode -- Grab the exact return code from the transaction
mcve_returnstatus -- Check to see if the transaction was successful
mcve_sale -- Send a SALE to MCVE
mcve_setblocking -- Set blocking/non-blocking mode for connection
mcve_setdropfile -- Set the connection method to Drop-File
mcve_setip -- Set the connection method to IP
mcve_setssl_files -- Set certificate key files and certificates if server requires client certificate verification
mcve_setssl -- Set the connection method to SSL
mcve_settimeout -- Set maximum transaction time (per trans)
mcve_settle -- Issue a settlement command to do a batch deposit
mcve_text_avs -- Get a textual representation of the return_avs
mcve_text_code -- Get a textual representation of the return_code
mcve_text_cv -- Get a textual representation of the return_cv
mcve_transactionauth -- Get the authorization number returned for the transaction (alpha-numeric)
mcve_transactionavs -- Get the Address Verification return status
mcve_transactionbatch -- Get the batch number associated with the transaction
mcve_transactioncv -- Get the CVC2/CVV2/CID return status
mcve_transactionid -- Get the unique system id for the transaction
mcve_transactionitem -- Get the ITEM number in the associated batch for this transaction
mcve_transactionssent -- Check to see if outgoing buffer is clear
mcve_transactiontext -- Get verbiage (text) return from MCVE or processing institution
mcve_transinqueue -- Number of transactions in client-queue
mcve_transnew -- Start a new transaction
mcve_transparam -- Add a parameter to a transaction
mcve_transsend -- Finalize and send the transaction
mcve_ub -- Get a list of all Unsettled batches
mcve_uwait -- Wait x microsecs
mcve_verifyconnection -- Set whether or not to PING upon connect to verify connection
mcve_verifysslcert -- Set whether or not to verify the server ssl certificate
mcve_void -- VOID a transaction in the settlement queue

LXXIV. Memcache Functions

Introduzione

Memcache module provides handy procedural and object oriented interface to memcached, highly effective caching daemon, which was especially designed to decrease database load in dynamic web applications.

This module doesn't have native support of multiple servers, but you still can implement it yourself in your application. Establish several memcached connections, set priority level for each server etc.

More information about memcached can be found at http://www.danga.com/memcached/.

Requisiti

This module uses functions of zlib to support on-the-fly data compression. Zlib is required to install this module.

PHP 4.3.3 or newer is required to use the memcache extension.

Installazione

In order to use these functions you must compile PHP with Memcache support by using the --enable-memcache[=DIR] option.

Windows users will enable php_memcache.dll inside of php.ini in order to use these functions. You may download this PECL extension DLL from the PHP Downloads page or at http://snaps.php.net/.

Costanti predefinite

Tabella 1. MemCache Constants

Name	Description
`MEMCACHE_COMPRESSED` (integer)	Used to turn on-the-fly data compression on with Memcache::set(), Memcache::add() e Memcache::replace().

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Tipi di risorse

There is only one resource type used in memcache module - it's the link identifier for a cache server connection.

Esempi

Esempio 1. memcache extension overview example
<?php $memcache = new Memcache; $memcache->connect('localhost', 11211) or die ("Could not connect"); $version = $memcache->getVersion(); echo "Server's version: ".$version."<br/>\n"; $tmp_object = new stdClass; $tmp_object->str_attr = 'test'; $tmp_object->int_attr = 123; $memcache->set('key', $tmp_object, false, 10) or die ("Failed to save data at the server"); echo "Store data in the cache (data will expire in 10 seconds)<br/>\n"; $get_result = $memcache->get('key'); echo "Data from the cache:<br/>\n"; var_dump($get_result); ?>

In the above example, an object is being saved in the cache and then retrieved back. Object and other non-scalar types are serialized before saving, so it's impossible to store resources (i.e. connection identifiers and others) in the cache.

Sommario
Memcache::add -- Add an item to the server
Memcache::close -- Close memcached server connection
Memcache::connect -- Open memcached server connection
memcache_debug -- Turn debug output on/off
Memcache::decrement -- Decrement item's value
Memcache::delete -- Delete item from the server
Memcache::flush -- Flush all existing items at the server
Memcache::get -- Retrieve item from the server
Memcache::getStats -- Get statistics of the server
Memcache::getVersion -- Return version of the server
Memcache::increment -- Increment item's value
Memcache::pconnect -- Open memcached server persistent connection
Memcache::replace -- Replace value of the existing item
Memcache::set -- Store data at the server

Memcache::add

(no version information, might be only in CVS)

Memcache::add -- Add an item to the server

Description

bool Memcache::add ( string key, mixed var [, int flag [, int expire]] )

Memcache::add() stores variable var with key only if such key doesn't exist at the server yet. Memcache::add() returns FALSE if such key already exist. For the rest Memcache::add() behaves similarly to Memcache::set().

Also you can use memcache_add() function. See example below.

Esempio 1. Memcache::add() example

<?php

$memcache_obj = memcache_connect("localhost", 11211);

/* procedural API */
memcache_add($memcache_obj, 'var_key', 'test variable', false, 30);

/* OO API */
$memcache_obj->add('var_key', 'test variable', false, 30);

?>

Memcache::add() returns TRUE on success or FALSE on failure.

See also Memcache::set(), Memcache::replace().

Memcache::close

(no version information, might be only in CVS)

Memcache::close -- Close memcached server connection

Description

bool Memcache::close ( void )

Memcache::close() closes connection to memcached server. This function doesn't close persistent connections, which are closed only during web-server shutdown/restart.

Also you can use memcache_close() function. See example below.

Esempio 1. Memcache::close() example

<?php

/* procedural API */
$memcache_obj = memcache_connect('memcache_host', 11211);
/* 
do something here ..
*/
memcache_close($memcache_obj);

/* OO API */
$memcache_obj = new Memcache;
$memcache_obj->connect('memcache_host', 11211);
/* 
do something here ..
*/
$memcache_obj->close();

?>

Memcache::close() returns FALSE if an error occured.

See also Memcache::connect(), Memcache::pconnect().

Memcache::connect

(no version information, might be only in CVS)

Memcache::connect -- Open memcached server connection

Description

bool Memcache::connect ( string host [, int port [, int timeout]] )

Memcache::connect() establishes a connection to the memcached server. Parameters host and port point to the host and port, where memcached is listening for connections. Parameter port is optional, it's default value is 11211. Also you can define a timeout (in seconds), which will be used when connecting to the daemon. Think twice before changing the default value - you can loose all the advantages of caching if your connection is too slow.

The connection, which was opened using Memcache::connect() will be automatically closed at the end of script execution. Also you can close it with Memcache::close().

Also you can use memcache_connect() function. See example below.

Esempio 1. Memcache::connect() example

<?php

/* procedural API */

$memcache_obj = memcache_connect('memcache_host', 11211);

/* OO API */

$memcache = new Memcache;
$memcache->connect('memcache_host', 11211);

?>

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

See also Memcache::pconnect() and Memcache::close().

memcache_debug

(PECL)

memcache_debug -- Turn debug output on/off

Description

bool memcache_debug ( int on_off )

memcache_debug() turns on debug output if parameter on_off is equal to 1 and turns off if it's 0.

Nota: memcache_debug() is accessible only if PHP was built with --enable-debug option and always returns TRUE in this case. Otherwise, this function has no effect and always returns FALSE.

Memcache::decrement

(no version information, might be only in CVS)

Memcache::decrement -- Decrement item's value

Description

int Memcache::decrement ( string key [, int value] )

Memcache::decrement() decrements value of the item by value. Similarly to Memcache::increment(), current value of the item is being converted to numerical and after that value is substracted.

Parameter value is optional. It's default is 1.

Nota: New item's value will not be less than zero.

Nota: Do not use Memcache::decrement() with item, which was stored compressed, because consequent call to Memcache::get() will fail.

Also you can use memcache_decrement() function. See example below.

Esempio 1. Memcache::decrement() example

<?php

/* procedural API */
$memcache_obj = memcache_connect('memcache_host', 11211);
/* decrement item by 2 */
$new_value = memcache_decrement($memcache_obj, 'test_item', 2);

/* OO API */
$memcache_obj = new Memcache;
$memcache_obj->connect('memcache_host', 11211);
/* decrement item by 3 */
$new_value = $memcache_obj->decrement('test_item', 3);
?>

<?php

/* procedural API */
$memcache_obj = memcache_connect('memcache_host', 11211);
$var = memcache_get($memcache_obj, 'some_key');

/* OO API */
$memcache_obj = new Memcache;
$memcache_obj->connect('memcache_host', 11211);
$var = $memcache_obj->get('some_key');

/* 
You also can use array of keys as a parameter.
If such item wasn't found at the server, the result
array simply will not include such key.
*/

/* procedural API */
$memcache_obj = memcache_connect('memcache_host', 11211);
$var = memcache_get($memcache_obj, Array('some_key', 'another_key'));

/* OO API */
$memcache_obj = new Memcache;
$memcache_obj->connect('memcache_host', 11211);
$var = $memcache_obj->get(Array('some_key', 'second_key'));

?>

Memcache::get() returns FALSE on failure or if such key was not found.

Memcache::getStats

(no version information, might be only in CVS)

Memcache::getStats -- Get statistics of the server

Description

array Memcache::getStats ( void )

Memcache::getStats() returns an associative array with server's statistics. Array keys correspond to stats parameters and values to parameter's values.

Also you can use memcache_get_stats() function.

Memcache::getStats() returns FALSE in case of an error.

Memcache::getVersion

(no version information, might be only in CVS)

Memcache::getVersion -- Return version of the server

Description

string Memcache::getVersion ( void )

Memcache::getVersion() returns a string with server's version number.

Also you can use memcache_get_version() function. See example below.

Esempio 1. Memcache::getVersion() example

<?php

/* procedural API */
$memcache_obj = memcache_connect('memcache_host', 11211);

echo memcache_get_version($memcache_obj);

/* OO API */
$memcache_obj = new Memcache;
echo $memcache_obj->getVersion();

?>

Memcache::getVersion() returns FALSE if an error occured.

Memcache::increment

(no version information, might be only in CVS)

Memcache::increment -- Increment item's value

Description

int Memcache::increment ( string key [, int value] )

Memcache::increment() increments value of the item on the specified value. If item with key key was not numeric and cannot be converted to number, it will change it's value to value.

Parameter value is optional. It's default value is 1.

Nota: Do not use Memcache::increment() with item, which was stored compressed, because consequent call to Memcache::get() will fail.

Also you can use memcache_increment() function. See example below.

Esempio 1. Memcache::increment() example

<?php

/* procedural API */
$memcache_obj = memcache_connect('memcache_host', 11211);
/* increment counter by 2 */
$current_value = memcache_increment($memcache_obj, 'counter', 2);

/* OO API */
$memcache_obj = new Memcache;
$memcache_obj->connect('memcache_host', 11211);
/* increment counter by 3 */
$current_value = $memcache_obj->increment('counter', 3);

?>

Memcache::increment() returns new item's value on success or FALSE on failure.

Memcache::increment() does not create an item if it didn't exist.

See also Memcache::decrement(), Memcache::replace().

Memcache::pconnect

(no version information, might be only in CVS)

Memcache::pconnect -- Open memcached server persistent connection

Description

bool Memcache::pconnect ( string host [, int port [, int timeout]] )

Memcache::pconnect() is similar to Memcache::connect() with the difference, that the connection it establishes is persistent. This connection is not closed after the end of script execution and by Memcache::close() function.

Also you can use memcache_pconnect() function. See example below.

Esempio 1. Memcache::pconnect() example

<?php

/* procedural API */
$memcache_obj = memcache_pconnect('memcache_host', 11211);

/* OO API */

$memcache_obj = new Memcache;
$memcache_obj->pconnect('memcache_host', 11211);

?>

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Memcache::replace

(no version information, might be only in CVS)

Memcache::replace -- Replace value of the existing item

Description

bool Memcache::replace ( string key, mixed var [, int flag [, int expire]] )

Memcache::replace() should be used to replace value of existing item with key. In case if item with such key doesn't exists, Memcache::replace() returns FALSE. For the rest Memcache::replace() behaves similarly to Memcache::set().

Also you can use memcache_replace() function. See example below.

Esempio 1. Memcache::replace() example

<?php

$memcache_obj = memcache_connect('memcache_host', 11211);

/* procedural API */
memcache_replace($memcache_obj, "test_key", "some variable", false, 30);

/* OO API */
$memcache_obj->replace("test_key", "some variable", false, 30);

?>

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

See also Memcache::set(), Memcache::add().

Memcache::set

(no version information, might be only in CVS)

Memcache::set -- Store data at the server

Description

bool Memcache::set ( string key, mixed var [, int flag [, int expire]] )

Memcache::set() stores an item var with key on the memcached server. Parameter expire is expiration time in seconds. If it's 0, the item never expires (but memcached server doesn't guarantee this item to be stored all the time, it could be deleted from the cache to make place for other items).

You can use MEMCACHE_COMPRESSED constant as flag value if you want to use on-the-fly compression (uses zlib).

Also you can use memcache_set() function. See example below.

Nota: Remember that resource variables (i.e. file and connection descriptors) cannot be stored in the cache, because they cannot be adequately represented in serialized state.

Esempio 1. Memcache::set() example

<?php
/* procedural API */

/* connect to memcached server */
$memcache_obj = memcache_connect('memcache_host', 11211);

/*
set value of item with key 'var_key'
using 0 as flag value, compression is not used
expire time is 30 seconds
*/
memcache_set($memcache_obj, 'var_key', 'some variable', 0, 30);

echo memcache_get($memcache_obj, 'var_key');

?>

Esempio 2. Memcache::set() example

<?php
/* OO API */

$memcache_obj = new Memcache;

/* connect to memcached server */
$memcache_obj->connect('memcache_host', 11211);

/*
set value of item with key 'var_key', using on-the-fly compression
expire time is 50 seconds
*/
$memcache_obj->set('var_key', 'some really big variable', MEMCACHE_COMPRESSED, 50);

echo $memcache_obj->get('var_key');

?>

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

See also Memcache::add(), Memcache::replace().

LXXV. Mhash Functions

Introduzione

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 documentation of mhash. 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.

Requisiti

To use it, download the mhash distribution from its web site and follow the included installation instructions.

Installazione

You need to compile PHP with the --with-mhash[=DIR] parameter to enable this extension. DIR is the mhash install directory.

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

Here is a list of hashes which are currently supported by mhash. If a hash is not listed here, but is listed by mhash 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_HAVAL256
MHASH_MD4
MHASH_MD5
MHASH_RIPEMD160
MHASH_SHA1
MHASH_SHA256
MHASH_TIGER
MHASH_TIGER128
MHASH_TIGER160

Esempi

Esempio 1. Compute 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"; ?>
This will produce:
The hash is d03cb659cbf9192dcd066272249f8412 The hmac is 750c783e6ab0b503eaa86e310a5db738

Sommario
mhash_count -- Get the highest available hash id
mhash_get_block_size -- Get the block size of the specified hash
mhash_get_hash_name -- Get the name of the specified hash
mhash_keygen_s2k -- Generates a key
mhash -- Compute hash

Esempio 1. mhash_get_hash_name() example
<?php $hash = MHASH_MD5; echo mhash_get_hash_name($hash); ?>
Il precedente esempio visualizzerà:
MD5

mhash_keygen_s2k

(PHP 4 >= 4.0.4, PHP 5)

mhash_keygen_s2k -- Generates a key

Description

string mhash_keygen_s2k ( int hash, string password, string salt, int bytes )

mhash_keygen_s2k() generates a key that is bytes long, from a user given password. This is the Salted S2K algorithm as specified in the OpenPGP document (RFC 2440). That algorithm will use the specified hash algorithm to create the key. The salt must be different and random enough for every key you generate in order to create different keys. That salt must be known when you check the keys, thus 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.

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.

mhash

(PHP 3 >= 3.0.9, PHP 4, PHP 5)

mhash -- Compute hash

Description

string mhash ( int hash, string data [, string key] )

mhash() applies a hash function specified by hash to the data and returns the resulting hash (also called digest). If the key is specified it will return the resulting HMAC. 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. In case of an error returns FALSE.

LXXVI. Mimetype Functions

Introduzione

Avvertimento

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.

Requisiti

Non sono necessarie librerie esterne per utilizzare questo modulo.

Installazione

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.

Nota: The configure option has been changed from --enable-mime-magic to --with-mime-magic since PHP 4.3.2

Nota: 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.

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.
Esempio 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

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

Tabella 1. Mimetype configuration options

Name	Default	Changeable	Changelog
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.

Per maggiori dettagli sulle costanti PHP_INI_* vedere Appendice G.

Breve descrizione dei parametri di configurazione.

mime_magic.debug bool: Enable/disable debugging.
mime_magic.magicfile string: The path to the magic.mime file.

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

Questa estensione non definisce alcuna costante.

Sommario
mime_content_type -- Detect MIME Content-type for a file

mime_content_type

(PHP 4 >= 4.3.0, PHP 5)

mime_content_type -- Detect MIME Content-type for a file

Description

string mime_content_type ( string filename )

Returns the MIME content type for a file as determined by using information from the magic.mime file. Content types are returned in MIME format, like text/plain or application/octet-stream.

Esempio 1. mime_content_type() example
<?php echo mime_content_type('php.gif') . "\n"; echo mime_content_type('test.php'); ?>
Il precedente esempio visualizzerà:
image/gif text/plain

LXXVII. Ming functions for Flash

Avvertimento

Introduzione

First of all: Ming is not an acronym. Ming is an open-source (LGPL) library which allows you to create SWF ("Flash") format movies. Ming supports almost all of Flash 4's features, including: shapes, gradients, bitmaps (pngs and jpegs), morphs ("shape tweens"), text, buttons, actions, sprites ("movie clips"), streaming mp3, and color transforms --the only thing that's missing is sound events.

Note that all values specifying length, distance, size, etc. are in "twips", twenty units per pixel. That's pretty much arbitrary, though, since the player scales the movie to whatever pixel size is specified in the embed/object tag, or the entire frame if not embedded.

Ming offers a number of advantages over the existing PHP/libswf module. You can use Ming anywhere you can compile the code, whereas libswf is closed-source and only available for a few platforms, Windows not one of them. Ming provides some insulation from the mundane details of the SWF file format, wrapping the movie elements in PHP objects. Also, Ming is still being maintained; if there's a feature that you want to see, just let us know ming@opaque.net.

Ming was added in PHP 4.0.5.

Requisiti

To use Ming with PHP, you first need to build and install the Ming library. Source code and installation instructions are available at the Ming home page: http://ming.sourceforge.net/ along with examples, a small tutorial, and the latest news.

Download the ming archive. Unpack the archive. Go in the Ming directory. make. make install.

This will build libming.so and install it into /usr/lib/, and copy ming.h into /usr/include/. Edit the PREFIX= line in the Makefile to change the installation directory.

Installazione

Esempio 1. built into PHP (Unix)

    mkdir <phpdir>/ext/ming
    cp php_ext/* <phpdir>/ext/ming
    cd <phpdir>
    ./buildconf
    ./configure --with-ming <other config options>


Build and install PHP as usual, restart web server if necessary.

Now either just add extension=php_ming.so to your php.ini file, or put dl('php_ming.so'); at the head of all of your Ming scripts.

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Tipi di risorse

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

SWFBUTTON_HIT (integer)
SWFBUTTON_DOWN (integer)
SWFBUTTON_OVER (integer)
SWFBUTTON_UP (integer)
SWFBUTTON_MOUSEUPOUTSIDE (integer)
SWFBUTTON_DRAGOVER (integer)
SWFBUTTON_DRAGOUT (integer)
SWFBUTTON_MOUSEUP (integer)
SWFBUTTON_MOUSEDOWN (integer)
SWFBUTTON_MOUSEOUT (integer)
SWFBUTTON_MOUSEOVER (integer)
SWFFILL_RADIAL_GRADIENT (integer)
SWFFILL_LINEAR_GRADIENT (integer)
SWFFILL_TILED_BITMAP (integer)
SWFFILL_CLIPPED_BITMAP (integer)
SWFTEXTFIELD_HASLENGTH (integer)
SWFTEXTFIELD_NOEDIT (integer)
SWFTEXTFIELD_PASSWORD (integer)
SWFTEXTFIELD_MULTILINE (integer)
SWFTEXTFIELD_WORDWRAP (integer)
SWFTEXTFIELD_DRAWBOX (integer)
SWFTEXTFIELD_NOSELECT (integer)
SWFTEXTFIELD_HTML (integer)
SWFTEXTFIELD_ALIGN_LEFT (integer)
SWFTEXTFIELD_ALIGN_RIGHT (integer)
SWFTEXTFIELD_ALIGN_CENTER (integer)
SWFTEXTFIELD_ALIGN_JUSTIFY (integer)
SWFACTION_ONLOAD (integer)
SWFACTION_ENTERFRAME (integer)
SWFACTION_UNLOAD (integer)
SWFACTION_MOUSEMOVE (integer)
SWFACTION_MOUSEDOWN (integer)
SWFACTION_MOUSEUP (integer)
SWFACTION_KEYDOWN (integer)
SWFACTION_KEYUP (integer)
SWFACTION_DATA (integer)

Classi predefinite

Queste classi sono definite da questa estensione, e sono disponibili solo quando l'estensione è stata compilata nel PHP o caricata come modulo dinamico al runtime.

Ming introduces 13 new objects in PHP, all with matching methods and attributes. To use them, you need to know about objects.

swfshape
swffill
swfgradient
swfbitmap
swftext
swftextfield
swffont
swfdisplayitem
swfmovie
swfbutton
swfaction
swfmorph
swfsprite

Sommario
ming_setcubicthreshold -- Set cubic threshold (?)
ming_setscale -- Set scale (?)
ming_useswfversion -- Use SWF version (?)
SWFAction -- Creates a new Action
SWFBitmap->getHeight -- Returns the bitmap's height
SWFBitmap->getWidth -- Returns the bitmap's width
SWFBitmap -- Loads Bitmap object
swfbutton_keypress -- Returns the action flag for keyPress(char)
SWFbutton->addAction -- Adds an action
SWFbutton->addShape -- Adds a shape to a button
SWFbutton->setAction -- Sets the action
SWFbutton->setdown -- Alias for addShape(shape, SWFBUTTON_DOWN)
SWFbutton->setHit -- Alias for addShape(shape, SWFBUTTON_HIT)
SWFbutton->setOver -- Alias for addShape(shape, SWFBUTTON_OVER)
SWFbutton->setUp -- Alias for addShape(shape, SWFBUTTON_UP)
SWFbutton -- Creates a new Button
SWFDisplayItem->addColor -- Adds the given color to this item's color transform
SWFDisplayItem->move -- Moves object in relative coordinates
SWFDisplayItem->moveTo -- Moves object in global coordinates
SWFDisplayItem->multColor -- Multiplies the item's color transform
SWFDisplayItem->remove -- Removes the object from the movie
SWFDisplayItem->Rotate -- Rotates in relative coordinates
SWFDisplayItem->rotateTo -- Rotates the object in global coordinates
SWFDisplayItem->scale -- Scales the object in relative coordinates
SWFDisplayItem->scaleTo -- Scales the object in global coordinates
SWFDisplayItem->setDepth -- Sets z-order
SWFDisplayItem->setName -- Sets the object's name
SWFDisplayItem->setRatio -- Sets the object's ratio
SWFDisplayItem->skewX -- Sets the X-skew
SWFDisplayItem->skewXTo -- Sets the X-skew
SWFDisplayItem->skewY -- Sets the Y-skew
SWFDisplayItem->skewYTo -- Sets the Y-skew
SWFDisplayItem -- Creates a new displayitem object
SWFFill->moveTo -- Moves fill origin
SWFFill->rotateTo -- Sets fill's rotation
SWFFill->scaleTo -- Sets fill's scale
SWFFill->skewXTo -- Sets fill x-skew
SWFFill->skewYTo -- Sets fill y-skew
SWFFill -- Loads SWFFill object
swffont->getwidth -- Returns the string's width
SWFFont -- Loads a font definition
SWFGradient->addEntry -- Adds an entry to the gradient list
SWFGradient -- Creates a gradient object
SWFMorph->getshape1 -- Gets a handle to the starting shape
SWFMorph->getshape2 -- Gets a handle to the ending shape
SWFMorph -- Creates a new SWFMorph object
SWFMovie->add -- Adds any type of data to a movie
SWFMovie->nextframe -- Moves to the next frame of the animation
SWFMovie->output -- Dumps your lovingly prepared movie out
swfmovie->remove -- Removes the object instance from the display list
SWFMovie->save -- Saves your movie in a file
SWFMovie->setbackground -- Sets the background color
SWFMovie->setdimension -- Sets the movie's width and height
SWFMovie->setframes -- Sets the total number of frames in the animation
SWFMovie->setrate -- Sets the animation's frame rate
SWFMovie->streammp3 -- Streams a MP3 file
SWFMovie -- Creates a new movie object, representing an SWF version 4 movie
SWFShape->addFill -- Adds a solid fill to the shape
SWFShape->drawCurve -- Draws a curve (relative)
SWFShape->drawCurveTo -- Draws a curve
SWFShape->drawLine -- Draws a line (relative)
SWFShape->drawLineTo -- Draws a line
SWFShape->movePen -- Moves the shape's pen (relative)
SWFShape->movePenTo -- Moves the shape's pen
SWFShape->setLeftFill -- Sets left rasterizing color
SWFShape->setLine -- Sets the shape's line style
SWFShape->setRightFill -- Sets right rasterizing color
SWFShape -- Creates a new shape object
swfsprite->add -- Adds an object to a sprite
SWFSprite->nextframe -- Moves to the next frame of the animation
SWFSprite->remove -- Removes an object to a sprite
SWFSprite->setframes -- Sets the total number of frames in the animation
SWFSprite -- Creates a movie clip (a sprite)
SWFText->addString -- Draws a string
SWFText->getWidth -- Computes string's width
SWFText->moveTo -- Moves the pen
SWFText->setColor -- Sets the current font color
SWFText->setFont -- Sets the current font
SWFText->setHeight -- Sets the current font height
SWFText->setSpacing -- Sets the current font spacing
SWFText -- Creates a new SWFText object
SWFTextField->addstring -- Concatenates the given string to the text field
SWFTextField->align -- Sets the text field alignment
SWFTextField->setbounds -- Sets the text field width and height
SWFTextField->setcolor -- Sets the color of the text field
SWFTextField->setFont -- Sets the text field font
SWFTextField->setHeight -- Sets the font height of this text field font
SWFTextField->setindentation -- Sets the indentation of the first line
SWFTextField->setLeftMargin -- Sets the left margin width of the text field
SWFTextField->setLineSpacing -- Sets the line spacing of the text field
SWFTextField->setMargins -- Sets the margins width of the text field
SWFTextField->setname -- Sets the variable name
SWFTextField->setrightMargin -- Sets the right margin width of the text field
SWFTextField -- Creates a text field object

The script syntax is based on the C language, but with a lot taken out- the SWF bytecode machine is just too simpleminded to do a lot of things we might like. For instance, we can't implement function calls without a tremendous amount of hackery because the jump bytecode has a hardcoded offset value. No pushing your calling address to the stack and returning- every function would have to know exactly where to return to.

So what's left? The compiler recognises the following tokens:

break
for
continue
if
else
do
while

There is no typed data; all values in the SWF action machine are stored as strings. The following functions can be used in expressions:

time(): Returns the number of milliseconds (?) elapsed since the movie started.
random(seed): Returns a pseudo-random number in the range 0-seed.
length(expr): Returns the length of the given expression.
int(number): Returns the given number rounded down to the nearest integer.
concat(expr, expr): Returns the concatenation of the given expressions.
ord(expr): Returns the ASCII code for the given character
chr(num): Returns the character for the given ASCII code
substr(string, location, length): Returns the substring of length length at location location of the given string string.

Additionally, the following commands may be used:

duplicateClip(clip, name, depth): Duplicate the named movie clip (aka sprite). The new movie clip has name name and is at depth depth.
removeClip(expr): Removes the named movie clip.
trace(expr): Write the given expression to the trace log. Doubtful that the browser plugin does anything with this.
startDrag(target, lock, [left, top, right, bottom]): Start dragging the movie clip target. The lock argument indicates whether to lock the mouse (?)- use 0 (FALSE) or 1 (TRUE). Optional parameters define a bounding area for the dragging.
stopDrag(): Stop dragging my heart around. And this movie clip, too.
callFrame(expr): Call the named frame as a function.
getURL(url, target, [method]): Load the given URL into the named target. The target argument corresponds to HTML document targets (such as "_top" or "_blank"). The optional method argument can be POST or GET if you want to submit variables back to the server.
loadMovie(url, target): Load the given URL into the named target. The target argument can be a frame name (I think), or one of the magical values "_level0" (replaces current movie) or "_level1" (loads new movie on top of current movie).
nextFrame(): Go to the next frame.
prevFrame(): Go to the last (or, rather, previous) frame.
play(): Start playing the movie.
stop(): Stop playing the movie.
toggleQuality(): Toggle between high and low quality.
stopSounds(): Stop playing all sounds.
gotoFrame(num): Go to frame number num. Frame numbers start at 0.
gotoFrame(name): Go to the frame named name. Which does a lot of good, since I haven't added frame labels yet.
setTarget(expr): Sets the context for action. Or so they say- I really have no idea what this does.

And there's one weird extra thing. The expression frameLoaded(num) can be used in if statements and while loops to check if the given frame number has been loaded yet. Well, it's supposed to, anyway, but I've never tested it and I seriously doubt it actually works. You can just use /:framesLoaded instead.

Movie clips (all together now- aka sprites) have properties. You can read all of them (or can you?), you can set some of them, and here they are:

x
y
xScale
yScale
currentFrame - (read-only)
totalFrames - (read-only)
alpha - transparency level
visible - 1=on, 0=off (?)
width - (read-only)
height - (read-only)
rotation
target - (read-only) (???)
framesLoaded - (read-only)
name
dropTarget - (read-only) (???)
url - (read-only) (???)
highQuality - 1=high, 0=low (?)
focusRect - (???)
soundBufTime - (???)

So, setting a sprite's x position is as simple as /box.x = 100;. Why the slash in front of the box, though? That's how flash keeps track of the sprites in the movie, just like a Unix filesystem- here it shows that box is at the top level. If the sprite named box had another sprite named biff inside of it, you'd set its x position with /box/biff.x = 100;. At least, I think so; correct me if I'm wrong here.

SWFBitmap swfbitmap ( mixed file [, mixed alphafile] )

Avvertimento

swfbitmap() creates a new SWFBitmap object from the Jpeg or DBL file in file. alphafile is a MSK file to be used as an alpha mask for a Jpeg image. Both parameters can be fopen() resources or binary strings.

Nota: We can only deal with baseline (frame 0) jpegs, no baseline optimized or progressive scan jpegs!

SWFBitmap has the following methods : swfbitmap->getwidth() and swfbitmap->getheight().

You can't import png images directly, though- have to use the png2dbl utility to make a dbl ("define bits lossless") file from the png. The reason for this is that I don't want a dependency on the png library in ming- autoconf should solve this, but that's not set up yet.
Esempio 1. Import PNG files
<?php $s = new SWFShape(); $f = $s->addFill(new SWFBitmap(file_get_contents("png.dbl"))); $s->setRightFill($f); $s->drawLine(32, 0); $s->drawLine(0, 32); $s->drawLine(-32, 0); $s->drawLine(0, -32); $m = new SWFMovie(); $m->setDimension(32, 32); $m->add($s); header('Content-type: application/x-shockwave-flash'); $m->output(); ?>

And you can put an alpha mask on a jpeg fill.
Esempio 2. swfbitmap() example
<?php $s = new SWFShape(); // .msk file generated with "gif2mask" utility $f = $s->addFill(new SWFBitmap(file_get_contents("alphafill.jpg"), file_get_contents("alphafill.msk"))); $s->setRightFill($f); $s->drawLine(640, 0); $s->drawLine(0, 480); $s->drawLine(-640, 0); $s->drawLine(0, -480); $c = new SWFShape(); $c->setRightFill($c->addFill(0x99, 0x99, 0x99)); $c->drawLine(40, 0); $c->drawLine(0, 40); $c->drawLine(-40, 0); $c->drawLine(0, -40); $m = new SWFMovie(); $m->setDimension(640, 480); $m->setBackground(0xcc, 0xcc, 0xcc); // draw checkerboard background for ($y=0; $y<480; $y+=40) { for ($x=0; $x<640; $x+=80) { $i = $m->add($c); $i->moveTo($x, $y); } $y+=40; for ($x=40; $x<640; $x+=80) { $i = $m->add($c); $i->moveTo($x, $y); } } $m->add($s); header('Content-type: application/x-shockwave-flash'); $m->output(); ?>

swfbutton_keypress

(PHP 4 >= 4.0.5)

swfbutton_keypress -- Returns the action flag for keyPress(char)

Description

int swfbutton_keypress ( string str )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

SWFbutton->addAction

(no version information, might be only in CVS)

SWFbutton->addAction -- Adds an action

Description

void swfbutton->addaction ( resource action, int flags )

Avvertimento

swfbutton->addaction() adds the action action to this button for the given conditions. The following flags are valid: SWFBUTTON_MOUSEOVER, SWFBUTTON_MOUSEOUT, SWFBUTTON_MOUSEUP, SWFBUTTON_MOUSEUPOUTSIDE, SWFBUTTON_MOUSEDOWN, SWFBUTTON_DRAGOUT and SWFBUTTON_DRAGOVER.

See also swfbutton->addshape() and swfaction().

SWFbutton->addShape

(no version information, might be only in CVS)

SWFbutton->addShape -- Adds a shape to a button

SWFButton swfbutton ( void )

Avvertimento

void swfdisplayitem->multcolor ( int red, int green, int blue [, int a] )

Avvertimento

swfdisplayitem->multcolor() multiplies the item's color transform by the given values.

The object may be a swfshape(), a swfbutton(), a swftext() or a swfsprite() object. It must have been added using the swfmovie->add().

This simple example will modify your picture's atmosphere to Halloween (use a landscape or bright picture).
Esempio 1. swfdisplayitem->multcolor() example
<?php $b = new SWFBitmap(file_get_contents("backyard.jpg")); // note use your own picture :-) $s = new SWFShape(); $s->setRightFill($s->addFill($b)); $s->drawLine($b->getWidth(), 0); $s->drawLine(0, $b->getHeight()); $s->drawLine(-$b->getWidth(), 0); $s->drawLine(0, -$b->getHeight()); $m = new SWFMovie(); $m->setDimension($b->getWidth(), $b->getHeight()); $i = $m->add($s); for ($n=0; $n<=20; ++$n) { $i->multColor(1.0-$n/10, 1.0, 1.0); $i->addColor(0xff*$n/20, 0, 0); $m->nextFrame(); } header('Content-type: application/x-shockwave-flash'); $m->output(); ?>

SWFDisplayItem->remove

(no version information, might be only in CVS)

SWFDisplayItem->remove -- Removes the object from the movie

SWFFont swffont ( string filename )

Avvertimento

If filename is the name of an FDB file (i.e., it ends in ".fdb"), load the font definition found in said file. Otherwise, create a browser-defined font reference.

FDB ("font definition block") is a very simple wrapper for the SWF DefineFont2 block which contains a full description of a font. One may create FDB files from SWT Generator template files with the included makefdb utility- look in the util directory off the main ming distribution directory.

Browser-defined fonts don't contain any information about the font other than its name. It is assumed that the font definition will be provided by the movie player. The fonts _serif, _sans, and _typewriter should always be available. For example:
<?php $f = newSWFFont("_sans"); ?>
will give you the standard sans-serif font, probably the same as what you'd get with <font name="sans-serif"> in HTML.

swffont() returns a reference to the font definition, for use in the swftext->setfont() and the swftextfield->setfont() methods.

SWFFont has the following methods : swffont->getwidth().

SWFGradient->addEntry

(no version information, might be only in CVS)

SWFGradient->addEntry -- Adds an entry to the gradient list

Description

void swfgradient->addentry ( float ratio, int red, int green, int blue [, int a] )

Avvertimento

swfgradient->addentry() adds an entry to the gradient list. ratio is a number between 0 and 1 indicating where in the gradient this color appears. Thou shalt add entries in order of increasing ratio.

red, green, blue is a color (RGB mode). Last parameter a is optional.

SWFGradient

(PHP 4 >= 4.0.5)

SWFGradient -- Creates a gradient object

Description

SWFGradient swfgradient ( void )

Avvertimento

swfgradient() creates a new SWFGradient object.

SWFMorph swfmorph ( void )

Avvertimento

swfmorph() creates a new SWFMorph object.

Also called a "shape tween". This thing lets you make those tacky twisting things that make your computer choke. Oh, joy!

The methods here are sort of weird. It would make more sense to just have newSWFMorph(shape1, shape2);, but as things are now, shape2 needs to know that it's the second part of a morph. (This, because it starts writing its output as soon as it gets drawing commands- if it kept its own description of its shapes and wrote on completion this and some other things would be much easier.)

SWFMorph has the following methods : swfmorph->getshape1() and swfmorph->getshape1().

This simple example will morph a big red square into a smaller blue black-bordered square.
Esempio 1. swfmorph() example
<?php $p = new SWFMorph(); $s = $p->getShape1(); $s->setLine(0, 0, 0, 0); /* Note that this is backwards from normal shapes (left instead of right). I have no idea why, but this seems to work.. */ $s->setLeftFill($s->addFill(0xff, 0, 0)); $s->movePenTo(-1000,-1000); $s->drawLine(2000,0); $s->drawLine(0,2000); $s->drawLine(-2000,0); $s->drawLine(0,-2000); $s = $p->getShape2(); $s->setLine(60,0,0,0); $s->setLeftFill($s->addFill(0, 0, 0xff)); $s->movePenTo(0,-1000); $s->drawLine(1000,1000); $s->drawLine(-1000,1000); $s->drawLine(-1000,-1000); $s->drawLine(1000,-1000); $m = new SWFMovie(); $m->setDimension(3000,2000); $m->setBackground(0xff, 0xff, 0xff); $i = $m->add($p); $i->moveTo(1500,1000); for ($r=0.0; $r<=1.0; $r+=0.1) { $i->setRatio($r); $m->nextFrame(); } header('Content-type: application/x-shockwave-flash'); $m->output(); ?>

SWFMovie->add

(no version information, might be only in CVS)

SWFMovie->add -- Adds any type of data to a movie

Description

void swfmovie->add ( resource instance )

Avvertimento

swfmovie->add() adds instance to the current movie. instance is any type of data : Shapes, text, fonts, etc. must all be added to the movie to make this work.

For displayable types (shape, text, button, sprite), this returns an swfdisplayitem(), a handle to the object in a display list. Thus, you can add the same shape to a movie multiple times and get separate handles back for each separate instance.

See also all other objects (adding this later), and swfmovie->remove()

See examples in : swfdisplayitem->rotateto() and swfshape->addfill().

SWFMovie->nextframe

(no version information, might be only in CVS)

SWFMovie->nextframe -- Moves to the next frame of the animation

Description

void swfmovie->nextframe ( void )

Avvertimento

swfmovie->nextframe() moves to the next frame of the animation.

SWFMovie->output

(no version information, might be only in CVS)

SWFMovie->output -- Dumps your lovingly prepared movie out

Description

int swfmovie->output ( [int compression] )

Avvertimento

swfmovie->output() dumps your lovingly prepared movie out. In PHP, preceding this with the command
<?php header('Content-type: application/x-shockwave-flash'); ?>
convinces the browser to display this as a flash movie.

The compression level can be a value between 0 and 9, defining the swf compression similar to gzip compression.

swfmovie->remove

(no version information, might be only in CVS)

swfmovie->remove -- Removes the object instance from the display list

Description

void swfmovie->remove ( resource instance )

Avvertimento

swfmovie->remove() removes the object instance instance from the display list.

SWFMovie->save

(no version information, might be only in CVS)

SWFMovie->save -- Saves your movie in a file

Description

int swfmovie->save ( string filename [, int compression] )

void swfmovie->streammp3 ( mixed mp3File )

Avvertimento

swfmovie->streammp3() streams the mp3 file mp3File. Not very robust in dealing with oddities (can skip over an initial ID3 tag, but that's about it). Like swfshape->addjpegfill(), this isn't a stable function- we'll probably need to make a separate SWFSound object to contain sound types. Parameter mp3File can be a fopen() resource or a binary string.

Note that the movie isn't smart enough to put enough frames in to contain the entire mp3 stream- you'll have to add (length of song * frames per second) frames to get the entire stream in.

Yes, now you can use ming to put that rock and roll devil worship music into your SWF files. Just don't tell the RIAA.
Esempio 1. swfmovie->streammp3() example
<?php $m = new SWFMovie(); $m->setRate(12.0); $m->streamMp3(file_get_contents("distortobass.mp3")); // use your own MP3 // 11.85 seconds at 12.0 fps = 142 frames $m->setFrames(142); header('Content-type: application/x-shockwave-flash'); $m->output(); ?>

SWFMovie

(PHP 4 >= 4.0.5)

SWFMovie -- Creates a new movie object, representing an SWF version 4 movie

Description

SWFMovie swfmovie ( void )

Avvertimento

swfmovie() creates a new movie object, representing an SWF version 4 movie.

SWFMovie has the following methods : swfmovie->output(),swfmovie->save(), swfmovie->add(), swfmovie->remove(), swfmovie->nextframe(), swfmovie->setbackground(), swfmovie->setrate(), swfmovie->setdimension(), swfmovie->setframes() and swfmovie->streammp3().

See examples in : swfdisplayitem->rotateto(), swfshape->setline(), swfshape->addfill()... Any example will use this object.

SWFShape->addFill

(no version information, might be only in CVS)

SWFShape->addFill -- Adds a solid fill to the shape

Description

SWFFill SWFShape->addFill ( int red, int green, int blue [, int a] )

SWFFill SWFShape->addFill ( SWFBitmap bitmap [, int flags] )

SWFFill SWFShape->addFill ( SWFGradient gradient [, int flags] )

Avvertimento

SWFShape->addFill() adds a solid fill to the shape's list of fill styles. SWFShape->addFill() accepts three different types of arguments.

red, green, blue is a color (RGB mode). Last parameter a is optional.

void swfshape->setleftfill ( swfgradient fill )

Avvertimento

void swfshape->setleftfill ( int red, int green, int blue [, int a] )

Avvertimento

What this nonsense is about is, every edge segment borders at most two fills. When rasterizing the object, it's pretty handy to know what those fills are ahead of time, so the swf format requires these to be specified.

swfshape->setleftfill() sets the fill on the left side of the edge- that is, on the interior if you're defining the outline of the shape in a counter-clockwise fashion. The fill object is an SWFFill object returned from one of the addFill functions above.

This seems to be reversed when you're defining a shape in a morph, though. If your browser crashes, just try setting the fill on the other side.

Shortcut for swfshape->setleftfill($s->addfill($r, $g, $b [, $a]));.

SWFShape->setLine

(no version information, might be only in CVS)

SWFShape->setLine -- Sets the shape's line style

Description

void swfshape->setline ( swfshape shape )

Avvertimento

void swfshape->setline ( int width, int red, int green, int blue [, int a] )

Avvertimento

swfshape->setline() sets the shape's line style. width is the line's width. If width is 0, the line's style is removed (then, all other arguments are ignored). If width > 0, then line's color is set to red, green, blue. Last parameter a is optional.

You must declare all line styles before you use them (see example).

This simple example will draw a big "!#%*@", in funny colors and gracious style.
Esempio 1. swfshape->setline() example
<?php $s = new SWFShape(); $f1 = $s->addFill(0xff, 0, 0); $f2 = $s->addFill(0xff, 0x7f, 0); $f3 = $s->addFill(0xff, 0xff, 0); $f4 = $s->addFill(0, 0xff, 0); $f5 = $s->addFill(0, 0, 0xff); // bug: have to declare all line styles before you use them $s->setLine(40, 0x7f, 0, 0); $s->setLine(40, 0x7f, 0x3f, 0); $s->setLine(40, 0x7f, 0x7f, 0); $s->setLine(40, 0, 0x7f, 0); $s->setLine(40, 0, 0, 0x7f); $f = new SWFFont('Techno.fdb'); $s->setRightFill($f1); $s->setLine(40, 0x7f, 0, 0); $s->drawGlyph($f, '!'); $s->movePen($f->getWidth('!'), 0); $s->setRightFill($f2); $s->setLine(40, 0x7f, 0x3f, 0); $s->drawGlyph($f, '#'); $s->movePen($f->getWidth('#'), 0); $s->setRightFill($f3); $s->setLine(40, 0x7f, 0x7f, 0); $s->drawGlyph($f, '%'); $s->movePen($f->getWidth('%'), 0); $s->setRightFill($f4); $s->setLine(40, 0, 0x7f, 0); $s->drawGlyph($f, '*'); $s->movePen($f->getWidth('*'), 0); $s->setRightFill($f5); $s->setLine(40, 0, 0, 0x7f); $s->drawGlyph($f, '@'); $m = new SWFMovie(); $m->setDimension(3000,2000); $m->setRate(12.0); $i = $m->add($s); $i->moveTo(1500-$f->getWidth("!#%*@")/2, 1000+$f->getAscent()/2); header('Content-type: application/x-shockwave-flash'); $m->output(); ?>

SWFShape->setRightFill

(no version information, might be only in CVS)

SWFShape->setRightFill -- Sets right rasterizing color

Description

void swfshape->setrightfill ( swfgradient fill )

Avvertimento

The optional flags change the text field's behavior. It has the following possibles values :

SWFTEXTFIELD_DRAWBOX draws the outline of the textfield
SWFTEXTFIELD_HASLENGTH
SWFTEXTFIELD_HTML allows text markup using HTML-tags
SWFTEXTFIELD_MULTILINE allows multiple lines
SWFTEXTFIELD_NOEDIT indicates that the field shouldn't be user-editable
SWFTEXTFIELD_NOSELECT makes the field non-selectable
SWFTEXTFIELD_PASSWORD obscures the data entry
SWFTEXTFIELD_WORDWRAP allows text to wrap

Flags are combined with the bitwise OR operation. For example,

<?php
$t = newSWFTextField(SWFTEXTFIELD_PASSWORD | SWFTEXTFIELD_NOEDIT); 
?>

creates a totally useless non-editable password field.

SWFTextField has the following methods : swftextfield->setfont(), swftextfield->setbounds(), swftextfield->align(), swftextfield->setheight(), swftextfield->setleftmargin(), swftextfield->setrightmargin(), swftextfield->setmargins(), swftextfield->setindentation(), swftextfield->setlinespacing(), swftextfield->setcolor(), swftextfield->setname() and swftextfield->addstring().

LXXVIII. Miscellaneous Functions

Introduzione

These functions were placed here because none of the other categories seemed to fit.

Requisiti

Non sono necessarie librerie esterne per utilizzare questo modulo.

Installazione

Non è necessaria nessuna installazione per usare queste funzioni, esse fanno parte del core di PHP.

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

Tabella 1. Misc. Configuration Options

Name	Default	Changeable
ignore_user_abort	"0"	PHP_INI_ALL
highlight.string	"#DD0000"	PHP_INI_ALL
highlight.comment	"#FF8000"	PHP_INI_ALL
highlight.keyword	"#007700"	PHP_INI_ALL
highlight.bg	"#FFFFFF"	PHP_INI_ALL
highlight.default	"#0000BB"	PHP_INI_ALL
highlight.html	"#000000"	PHP_INI_ALL
browscap	NULL	PHP_INI_SYSTEM

Per maggiori dettagli sulle costanti PHP_INI_* vedere Appendice G.

Breve descrizione dei parametri di configurazione.

ignore_user_abort boolean

TRUE by default. If changed to FALSE scripts will be terminated as soon as they try to output something after a client has aborted their connection.

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

CONNECTION_ABORTED (integer)
CONNECTION_NORMAL (integer)
CONNECTION_TIMEOUT (integer)
__COMPILER_HALT_OFFSET__ (integer): Added in PHP 5.1.

Sommario
connection_aborted -- Returns TRUE if client disconnected
connection_status -- Returns connection status bitfield
connection_timeout -- Return TRUE if script timed out
constant -- Returns the value of a constant
define -- Defines a named constant
defined -- Checks whether a given named constant exists
die -- Equivalent to exit()
eval -- Evaluate a string as PHP code
exit -- Output a message and terminate the current script
get_browser -- Tells what the user's browser is capable of
__halt_compiler -- Halts the compiler execution
highlight_file -- Syntax highlighting of a file
highlight_string -- Syntax highlighting of a string
ignore_user_abort -- Set whether a client disconnect should abort script execution
pack -- Pack data into binary string
php_check_syntax -- Check the PHP syntax of (and execute) the specified file
php_strip_whitespace -- Return source with stripped comments and whitespace
show_source -- Alias di highlight_file()
sleep -- Delay execution
time_nanosleep -- Delay for a number of seconds and nanoseconds
time_sleep_until -- Make the script sleep until the specified time
uniqid -- Generate a unique ID
unpack -- Unpack data from binary string
usleep -- Delay execution in microseconds

constant() is useful if you need to retrieve the value of a constant, but do not know its name. I.e. it is stored in a variable or returned by a function.

This function works also with class constants.

Esempio 1. constant() example
<?php define("MAXSIZE", 100); echo MAXSIZE; echo constant("MAXSIZE"); // same thing as the previous line ?>

See also define(), defined() and the section on Constants.

define

(PHP 3, PHP 4, PHP 5)

define -- Defines a named constant

Description

bool define ( string name, mixed value [, bool case_insensitive] )

Defines a named constant. See the section on constants for more details.

The name of the constant is given by name; the value is given by value.

The optional third parameter case_insensitive is also available. If the value TRUE is given, then the constant will be defined case-insensitive. The default behaviour is case-sensitive; i.e. CONSTANT and Constant represent different values.

Esempio 1. Defining Constants
<?php define("CONSTANT", "Hello world."); echo CONSTANT; // outputs "Hello world." echo Constant; // outputs "Constant" and issues a notice. define("GREETING", "Hello you.", true); echo GREETING; // outputs "Hello you." echo Greeting; // outputs "Hello you." ?>

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

See also defined(), constant() and the section on Constants.

defined

(PHP 3, PHP 4, PHP 5)

defined -- Checks whether a given named constant exists

Description

bool defined ( string name )

Returns TRUE if the named constant given by name has been defined, FALSE otherwise.

Esempio 1. Checking Constants
<?php /* Note the use of quotes, this is important. This example is checking * if the string 'CONSTANT' is the name of a constant named CONSTANT */ if (defined('CONSTANT')) { echo CONSTANT; } ?>

Nota: If you want to see if a variable exists, use isset() as defined() only applies to constants. If you want to see if a function exists, use function_exists().

See also define(), constant(), get_defined_constants(), function_exists(), and the section on Constants.

die

(PHP 3, PHP 4, PHP 5)

die -- Equivalent to exit()

Description

This language construct is equivalent to exit().

eval

(PHP 3, PHP 4, PHP 5)

eval -- Evaluate a string as PHP code

Description

mixed eval ( string code_str )

eval() evaluates the string given in code_str as PHP code. Among other things, this can be useful for storing code in a database text field for later execution.

There are some factors to keep in mind when using eval(). Remember that the string passed must be valid PHP code, including things like terminating statements with a semicolon so the parser doesn't die on the line after the eval(), and properly escaping things in code_str.

Also remember that variables given values under eval() will retain these values in the main script afterwards.

A return statement will terminate the evaluation of the string immediately. As of PHP 4, eval() returns NULL unless return is called in the evaluated code, in which case the value passed to return is returned. In case of a parse error in the evaluated code, eval() returns FALSE. In case of a fatal error in the evaluated code, the whole script exits. In PHP 3, eval() does not return a value.

Esempio 1. eval() example - simple text merge
<?php $string = 'cup'; $name = 'coffee'; $str = 'This is a $string with my $name in it.'; echo $str. "\n"; eval("\$str = \"$str\";"); echo $str. "\n"; ?>
Il precedente esempio visualizzerà:
This is a $string with my $name in it. This is a cup with my coffee in it.

Suggerimento: Come con qualsiasi cosa che invia il risultato direttamente al browser, è possibile utilizzare la funzione output-control per catturare l'uscita di questa funzione e salvarla - per esempio - in una stringa.

exit

(PHP 3, PHP 4, PHP 5)

exit -- Output a message and terminate the current script

Description

void exit ( [string status] )

void exit ( int status )

Nota: This is not a real function, but a language construct.

Nota: PHP >= 4.2.0 does NOT print the status if it is an integer.

The exit() function terminates execution of the script. It prints status just before exiting.

If status is an integer, that value will also be used as the exit status. Exit statuses should be in the range 0 to 254, the exit status 255 is reserved by PHP and shall not be used. The status 0 is used to terminate the program successfully.

Esempio 1. exit() example
<?php $filename = '/path/to/data-file'; $file = fopen($filename, 'r') or exit("unable to open file ($filename)"); ?>

Esempio 2. exit() status example
<?php //exit program normally exit; exit(); exit(0); //exit with an error code exit(1); exit(0376); //octal ?>

Nota: The die() function is an alias for exit().

get_browser

(PHP 3, PHP 4, PHP 5)

get_browser -- Tells what the user's browser is capable of

Description

mixed get_browser ( [string user_agent [, bool return_array]] )

get_browser() attempts to determine the capabilities of the user's browser. This is done by looking up the browser's information in the browscap.ini file.

By default, the value of HTTP User-Agent header is used; however, you can alter this (i.e., look up another browser's info) by passing the optional user_agent parameter to get_browser(). You can bypass user_agent parameter with NULL value.

The information is returned in an object, which will contain various data elements representing, for instance, the browser's major and minor version numbers and ID string; TRUE/FALSE values for features such as frames, JavaScript, and cookies; and so forth.

As of PHP 4.3.2, if the optional parameter return_array is TRUE, this function will return an array instead of an object.

Esempio 1. Listing all information about the users browser
<?php echo $_SERVER['HTTP_USER_AGENT'] . "\n\n"; $browser = get_browser(null, true); print_r($browser); ?>
Il precedente esempio visualizzerà qualcosa simile a:
Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.7) Gecko/20040803 Firefox/0.9.3 Array ( [browser_name_regex] => ^mozilla/5\.0 (windows; .; windows nt 5\.1; .*rv:.*) gecko/.* firefox/0\.9.*$ [browser_name_pattern] => Mozilla/5.0 (Windows; ?; Windows NT 5.1; *rv:*) Gecko/* Firefox/0.9* [parent] => Firefox 0.9 [platform] => WinXP [browser] => Firefox [version] => 0.9 [majorver] => 0 [minorver] => 9 [css] => 2 [frames] => 1 [iframes] => 1 [tables] => 1 [cookies] => 1 [backgroundsounds] => [vbscript] => [javascript] => 1 [javaapplets] => 1 [activexcontrols] => [cdf] => [aol] => [beta] => 1 [win16] => [crawler] => [stripper] => [wap] => [netclr] => )

The cookies value simply means that the browser itself is capable of accepting cookies and does not mean the user has enabled the browser to accept cookies or not. The only way to test if cookies are accepted is to set one with setcookie(), reload, and check for the value.

Nota: In order for this to work, your browscap configuration setting in php.ini must point to the correct location of the browscap.ini file on your system.
browscap.ini is not bundled with PHP, but you may find an up-to-date php_browscap.ini file here.
While browscap.ini contains information on many browsers, it relies on user updates to keep the database current. The format of the file is fairly self-explanatory.

__halt_compiler

(no version information, might be only in CVS)

__halt_compiler -- Halts the compiler execution

Descrizione

void __halt_compiler ( void )

This function halts the execution of the compiler. This can be useful to embed data in PHP scripts, like the installation files. Byte position of the data start can be determined by the __COMPILER_HALT_OFFSET__ constant which is defined only if there is a __halt_compiler() presented in the file.

Nota: __halt_compiler() can only be used from the outermost scope.

Esempi

Esempio 1. A __halt_compiler() example
<?php // open this file $fp = fopen(__FILE__, 'r'); // seek file pointer to data fseek($fp, __COMPILER_HALT_OFFSET__); // and output it var_dump(stream_get_contents($fp)); // the end of the script execution __halt_compiler();the instalation data (eg. tar, gz, PHP, etc..)

highlight_file

(PHP 4, PHP 5)

highlight_file -- Syntax highlighting of a file

Description

mixed highlight_file ( string filename [, bool return] )

The highlight_file() function prints out a syntax highlighted version of the code contained in filename using the colors defined in the built-in syntax highlighter for PHP.

If the second parameter return is set to TRUE then highlight_file() will return the highlighted code as a string instead of printing it out. If the second parameter is not set to TRUE then highlight_file() will return TRUE on success, FALSE on failure.

Nota: The return parameter became available in PHP 4.2.0. Before this time it behaved like the default, which is FALSE

Nota: Since PHP 4.2.1 this function is also affected by safe_mode and open_basedir.

Attenzione

Care should be taken when using the highlight_file() function to make sure that you do not inadvertently reveal sensitive information such as passwords or any other type of information that might create a potential security risk.

Many servers are configured to automatically highlight files with a phps extension. For example, example.phps when viewed will show the syntax highlighted source of the file. To enable this, add this line to the httpd.conf:

AddType application/x-httpd-php-source .phps

highlight_string

(PHP 4, PHP 5)

highlight_string -- Syntax highlighting of a string

Description

mixed highlight_string ( string str [, bool return] )

The highlight_string() function outputs a syntax highlighted version of str using the colors defined in the built-in syntax highlighter for PHP.

If the second parameter return is set to TRUE then highlight_string() will return the highlighted code as a string instead of printing it out. If the second parameter is not set to TRUE then highlight_string() will return TRUE on success, FALSE on failure.

Esempio 1. highlight_string() example
<?php highlight_string('<?php phpinfo(); ?>'); ?>
The above example will output (in PHP 4):
<code><font color="#000000"> <font color="#0000BB"><?php phpinfo</font><font color="#007700">(); </font><font color="#0000BB">?></font> </font> </code>
The above example will output (in PHP 5):
<code><span style="color: #000000"> <span style="color: #0000BB"><?php phpinfo</span><span style="color: #007700">(); </span><span style="color: #0000BB">?></span> </span> </code>

Nota: The return parameter became available in PHP 4.2.0. Before this time it behaved like the default, which is FALSE

ignore_user_abort

(PHP 3 >= 3.0.7, PHP 4, PHP 5)

ignore_user_abort -- Set whether a client disconnect should abort script execution

Description

int ignore_user_abort ( [bool setting] )

This function sets whether a client disconnect should cause a script to be aborted. It will return the previous setting and can be called without an argument to not change the current setting and only return the current setting. See the Connection Handling section in the Features chapter for a complete description of connection handling in PHP.

pack

(PHP 3, PHP 4, PHP 5)

pack -- Pack data into binary string

Description

string pack ( string format [, mixed args [, mixed ...]] )

Pack given arguments into binary string according to format. Returns binary string containing data.

The idea to this function was taken from Perl and all formatting codes work the same as there, however, there are some formatting codes that are missing such as Perl's "u" format code. The format string consists of format codes followed by an optional repeater argument. The repeater argument can be either an integer value or * for repeating to the end of the input data. For a, A, h, H the repeat count specifies how many characters of one data argument are taken, for @ it is the absolute position where to put the next data, for everything else the repeat count specifies how many data arguments are consumed and packed into the resulting binary string. Currently implemented are

Tabella 1. pack() format characters

Code	Description
a	NUL-padded string
A	SPACE-padded string
h	Hex string, low nibble first
H	Hex string, high nibble first
c	signed char
C	unsigned char
s	signed short (always 16 bit, machine byte order)
S	unsigned short (always 16 bit, machine byte order)
n	unsigned short (always 16 bit, big endian byte order)
v	unsigned short (always 16 bit, little endian byte order)
i	signed integer (machine dependent size and byte order)
I	unsigned integer (machine dependent size and byte order)
l	signed long (always 32 bit, machine byte order)
L	unsigned long (always 32 bit, machine byte order)
N	unsigned long (always 32 bit, big endian byte order)
V	unsigned long (always 32 bit, little endian byte order)
f	float (machine dependent size and representation)
d	double (machine dependent size and representation)
x	NUL byte
X	Back up one byte
@	NUL-fill to absolute position

Esempio 1. pack() example
<?php $binarydata = pack("nvc*", 0x1234, 0x5678, 65, 66); ?>
The resulting binary string will be 6 bytes long and contain the byte sequence 0x12, 0x34, 0x78, 0x56, 0x41, 0x42.

Note that the distinction between signed and unsigned values only affects the function unpack(), where as function pack() gives the same result for signed and unsigned format codes.

Also note that PHP internally stores integer values as signed values of a machine dependent size. If you give it an unsigned integer value too large to be stored that way it is converted to a float which often yields an undesired result.

php_check_syntax

(PHP 5 <= 5.0.4)

php_check_syntax -- Check the PHP syntax of (and execute) the specified file

Descrizione

bool php_check_syntax ( string file_name [, string &error_message] )

For technical reasons, this function is deprecated and removed from PHP. Instead, use php -l somefile.php from the commandline.

The php_check_syntax() function performs a syntax (lint) check on the specified filename testing for scripting errors. This is similar to using php -l from the commandline except php_check_syntax() will execute (but not output) the checked file_name. For example, if a function is defined in file_name, this defined function will be available to the file that executed php_check_syntax(), but output from file_name will be suppressed.

Elenco dei parametri

file_name: The name of the file being checked.
error_message: If the error_message parameter is used, it will contain the error message generated by the syntax check. error_message is passed by reference.

Valori restituiti

Returns TRUE if the lint check passed, and FALSE if the link check failed or if file_name cannot be opened.

Log delle modifiche

Versione	Descrizione
5.0.5	This function was removed from PHP.
5.0.3	Calling exit() after php_check_syntax() resulted in a Segfault.
5.0.1	`error_message` is passed by reference.

Esempi

php -l somefile.php

Il precedente esempio visualizzerà qualcosa simile a:

PHP Parse error: unexpected T_STRING in /tmp/somefile.php on line 81

Vedere anche:

include()

is_readable()

php_strip_whitespace

(PHP 5)

php_strip_whitespace -- Return source with stripped comments and whitespace

Descrizione

string php_strip_whitespace ( string filename )

Returns the PHP source code in filename with PHP comments and whitespace removed. This may be useful for determining the amount of actual code in your scripts compared with the amount of comments. This is similar to using php -w from the commandline.

Nota: This function works as described as of PHP 5.0.1. Before this it would only return an empty string. For more information on this bug and its prior behavior, see bug report #29606.

Valori restituiti

The stripped source code will be returned on success, or an empty string on failure.

Esempi

Esempio 1. php_strip_whitespace() example
<?php // PHP comment here /* * Another PHP comment */ echo php_strip_whitespace(__FILE__); // Newlines are considered whitespace, and are removed too: do_nothing(); ?>
Il precedente esempio visualizzerà:
<?php echo php_strip_whitespace(__FILE__); do_nothing(); ?>
Notice the PHP comments are gone, as are the whitespace and newline after the first echo statement.

show_source

(PHP 4, PHP 5)

show_source -- Alias di highlight_file()

Descrizione

This function is an alias of: highlight_file().

sleep

(PHP 3, PHP 4, PHP 5)

sleep -- Delay execution

Description

int sleep ( int seconds )

The sleep() function delays program execution for the given number of seconds.

Esempio 1. sleep() example
<?php // current time echo date('h:i:s') . "\n"; // sleep for 10 seconds sleep(10); // wake up ! echo date('h:i:s') . "\n"; ?>
This example will output (after 10 seconds)
05:31:23 05:31:33

See also usleep() and set_time_limit()

time_nanosleep

(PHP 5)

time_nanosleep -- Delay for a number of seconds and nanoseconds

Descrizione

mixed time_nanosleep ( int seconds, int nanoseconds )

Delays program execution for the given number of seconds and nanoseconds.

seconds must be a positive integer, and nanoseconds must be a positive integer less than 1 billion.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

If the delay was interrupted by a signal, an associative array will be returned with the components:

seconds - number of seconds remaining in the delay
nanoseconds - number of nanoseconds remaining in the delay

Vedere anche:

sleep(), usleep(), set_time_limit()

Esempi

Esempio 1. time_nanosleep() example
<?php // Careful! This won't work as expected if an array is returned if (time_nanosleep(0, 500000000)) { echo "Slept for half a second.\n"; } // This is better: if (time_nanosleep(0, 500000000) === true) { echo "Slept for half a second.\n"; } // And this is the best: $nano = time_nanosleep(2, 100000); if ($nano === true) { echo "Slept for 2 seconds, 100 milliseconds.\n"; } elseif ($nano === false) { echo "Sleeping failed.\n"; } elseif (is_array($nano)) { $seconds = $nano['seconds']; $nanoseconds = $nano['nanoseconds']; echo "Interrupted by a signal.\n"; echo "Time remaining: $seconds seconds, $nanoseconds nanoseconds."; } ?>

Nota: Questa funzione non è implementata su piattaforme Windows

time_sleep_until

(PHP 5 >= 5.1.0RC1)

time_sleep_until -- Make the script sleep until the specified time

Descrizione

bool time_sleep_until ( float timestamp )

This function will make the script sleep until the specified timestamp. If the specified timestamp is in the past, time_sleep_until() will generate a E_WARNING and return FALSE.

Nota: Questa funzione non è implementata su piattaforme Windows

Elenco dei parametri

timestamp: The timestamp when the script should wake.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 1. A time_sleep_until() example
<?php //returns false and generates a warning var_dump(time_sleep_until(time()-1)); // may only work on faster computers, will sleep up to 0.2 seconds var_dump(time_sleep_until(time()+0.2)); ?>

Vedere anche:

sleep()

usleep()

time_nanosleep()

uniqid

(PHP 3, PHP 4, PHP 5)

uniqid -- Generate a unique ID

Description

string uniqid ( [string prefix [, bool more_entropy]] )

uniqid() returns a prefixed unique identifier based on the current time in microseconds. prefix is optional but can be useful, for instance, if you generate identifiers simultaneously on several hosts that might happen to generate the identifier at the same microsecond. Up until PHP 4.3.1, prefix could only be a maximum of 114 characters long.

If the optional more_entropy parameter is TRUE, uniqid() will add additional entropy (using the combined linear congruential generator) at the end of the return value, which should make the results more unique.

With an empty prefix, the returned string will be 13 characters long. If more_entropy is TRUE, it will be 23 characters.

Nota: The prefix parameter became optional in PHP 5.

If you need a unique identifier or token and you intend to give out that token to the user via the network (i.e. session cookies), it is recommended that you use something along these lines:

<?php
// no prefix
$token = md5(uniqid());

// better, difficult to guess
$better_token = md5(uniqid(rand(), true));
?>

This will create a 32 character identifier (a 128 bit hex number) that is extremely difficult to predict.

unpack

(PHP 3, PHP 4, PHP 5)

unpack -- Unpack data from binary string

Description

array unpack ( string format, string data )

unpack() from binary string into array according to format. Returns array containing unpacked elements of binary string.

unpack() works slightly different from Perl as the unpacked data is stored in an associative array. To accomplish this you have to name the different format codes and separate them by a slash /.
Esempio 1. unpack() example
<?php $array = unpack("c2chars/nint", $binarydata); ?>
The resulting array will contain the entries "chars1", "chars2" and "int".

Attenzione

Note that PHP internally stores integral values as signed. If you unpack a large unsigned long and it is of the same size as PHP internally stored values the result will be a negative number even though unsigned unpacking was specified.

See also pack() for an explanation of the format codes.

usleep

(PHP 3, PHP 4, PHP 5)

usleep -- Delay execution in microseconds

Description

void usleep ( int micro_seconds )

The usleep() function delays program execution for the given number of micro_seconds. A microsecond is one millionth of a second.

Esempio 1. usleep() example
<?php // Current time echo date('h:i:s') . "\n"; // wait for 2 secondes usleep(2000000); // back! echo date('h:i:s') . "\n"; ?>
This script will output :
11:13:28 11:13:30

Nota: This function did not work on Windows systems until PHP 5.0.0

See also sleep() and set_time_limit().

LXXIX. mnoGoSearch Functions

Introduzione

These functions allow you to access the mnoGoSearch (former UdmSearch) free search engine. mnoGoSearch is a full-featured search engine software for intranet and internet servers, distributed under the GNU license. mnoGoSearch has a number of unique features, which makes it appropriate for a wide range of applications from search within your site to a specialized search system such as cooking recipes or newspaper search, FTP archive search, news articles search, etc. It offers full-text indexing and searching for HTML, PDF, and text documents. mnoGoSearch consists of two parts. The first is an indexing mechanism (indexer). The purpose of the indexer is to walk through HTTP, FTP, NEWS servers or local files, recursively grabbing all the documents and storing meta-data about that documents in a SQL database in a smart and effective manner. After every document is referenced by its corresponding URL, meta-data is collected by the indexer for later use in a search process. The search is performed via Web interface. C, CGI, PHP and Perl search front ends are included.

More information about mnoGoSearch can be found at http://www.mnogosearch.org/.

Nota: Questo modulo è stato spostato nel repository PECL e non sarà più rilascio con il PHP dalla versione 5.1.0.

Nota: Questo modulo non è disponibile su piattaforme Windows.

Requisiti

Download mnoGosearch from http://www.mnogosearch.org/ and install it on your system. You need at least version 3.1.10 of mnoGoSearch installed to use these functions.

Installazione

In order to have these functions available, you must compile PHP with mnoGosearch support by using the --with-mnogosearchoption. If you use this option without specifying the path to mnoGosearch, PHP will look for mnoGosearch under /usr/local/mnogosearch path by default. If you installed mnoGosearch at a different location you should specify it: --with-mnogosearch=DIR.

Nota: PHP contains built-in MySQL access library, which can be used to access MySQL. It is known that mnoGoSearch is not compatible with this built-in library and can work only with generic MySQL libraries. Thus, if you use mnoGoSearch with MySQL, during PHP configuration you have to indicate the directory of your MySQL installation, that was used during mnoGoSearch configuration, i.e. for example: --with-mnogosearch --with-mysql=/usr.

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Tipi di risorse

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

UDM_FIELD_URLID (integer)
UDM_FIELD_URL (integer)
UDM_FIELD_CONTENT (integer)
UDM_FIELD_TITLE (integer)
UDM_FIELD_KEYWORDS (integer)
UDM_FIELD_DESC (integer)
UDM_FIELD_DESCRIPTION (integer)
UDM_FIELD_TEXT (integer)
UDM_FIELD_SIZE (integer)
UDM_FIELD_RATING (integer)
UDM_FIELD_SCORE (integer)
UDM_FIELD_MODIFIED (integer)
UDM_FIELD_ORDER (integer)
UDM_FIELD_CRC (integer)
UDM_FIELD_CATEGORY (integer)
UDM_FIELD_LANG (integer)
UDM_FIELD_CHARSET (integer)
UDM_PARAM_PAGE_SIZE (integer)
UDM_PARAM_PAGE_NUM (integer)
UDM_PARAM_SEARCH_MODE (integer)
UDM_PARAM_CACHE_MODE (integer)
UDM_PARAM_TRACK_MODE (integer)
UDM_PARAM_PHRASE_MODE (integer)
UDM_PARAM_CHARSET (integer)
UDM_PARAM_LOCAL_CHARSET (integer)
UDM_PARAM_BROWSER_CHARSET (integer)
UDM_PARAM_STOPTABLE (integer)
UDM_PARAM_STOP_TABLE (integer)
UDM_PARAM_STOPFILE (integer)
UDM_PARAM_STOP_FILE (integer)
UDM_PARAM_WEIGHT_FACTOR (integer)
UDM_PARAM_WORD_MATCH (integer)
UDM_PARAM_MAX_WORD_LEN (integer)
UDM_PARAM_MAX_WORDLEN (integer)
UDM_PARAM_MIN_WORD_LEN (integer)
UDM_PARAM_MIN_WORDLEN (integer)
UDM_PARAM_ISPELL_PREFIXES (integer)
UDM_PARAM_ISPELL_PREFIX (integer)
UDM_PARAM_PREFIXES (integer)
UDM_PARAM_PREFIX (integer)
UDM_PARAM_CROSS_WORDS (integer)
UDM_PARAM_CROSSWORDS (integer)
UDM_PARAM_VARDIR (integer)
UDM_PARAM_DATADIR (integer)
UDM_PARAM_HLBEG (integer)
UDM_PARAM_HLEND (integer)
UDM_PARAM_SYNONYM (integer)
UDM_PARAM_SEARCHD (integer)
UDM_PARAM_QSTRING (integer)
UDM_PARAM_REMOTE_ADDR (integer)
UDM_LIMIT_CAT (integer)
UDM_LIMIT_URL (integer)
UDM_LIMIT_TAG (integer)
UDM_LIMIT_LANG (integer)
UDM_LIMIT_DATE (integer)
UDM_PARAM_FOUND (integer)
UDM_PARAM_NUM_ROWS (integer)
UDM_PARAM_WORDINFO (integer)
UDM_PARAM_WORD_INFO (integer)
UDM_PARAM_SEARCHTIME (integer)
UDM_PARAM_SEARCH_TIME (integer)
UDM_PARAM_FIRST_DOC (integer)
UDM_PARAM_LAST_DOC (integer)
UDM_MODE_ALL (integer)
UDM_MODE_ANY (integer)
UDM_MODE_BOOL (integer)
UDM_MODE_PHRASE (integer)
UDM_CACHE_ENABLED (integer)
UDM_CACHE_DISABLED (integer)
UDM_TRACK_ENABLED (integer)
UDM_TRACK_DISABLED (integer)
UDM_PHRASE_ENABLED (integer)
UDM_PHRASE_DISABLED (integer)
UDM_CROSS_WORDS_ENABLED (integer)
UDM_CROSSWORDS_ENABLED (integer)
UDM_CROSS_WORDS_DISABLED (integer)
UDM_CROSSWORDS_DISABLED (integer)
UDM_PREFIXES_ENABLED (integer)
UDM_PREFIX_ENABLED (integer)
UDM_ISPELL_PREFIXES_ENABLED (integer)
UDM_ISPELL_PREFIX_ENABLED (integer)
UDM_PREFIXES_DISABLED (integer)
UDM_PREFIX_DISABLED (integer)
UDM_ISPELL_PREFIXES_DISABLED (integer)
UDM_ISPELL_PREFIX_DISABLED (integer)
UDM_ISPELL_TYPE_AFFIX (integer)
UDM_ISPELL_TYPE_SPELL (integer)
UDM_ISPELL_TYPE_DB (integer)
UDM_ISPELL_TYPE_SERVER (integer)
UDM_MATCH_WORD (integer)
UDM_MATCH_BEGIN (integer)
UDM_MATCH_SUBSTR (integer)
UDM_MATCH_END (integer)

Sommario
udm_add_search_limit -- Add various search limits
udm_alloc_agent_array -- Allocate mnoGoSearch session
udm_alloc_agent -- Allocate mnoGoSearch session
udm_api_version -- Get mnoGoSearch API version
udm_cat_list -- Get all the categories on the same level with the current one
udm_cat_path -- Get the path to the current category
udm_check_charset -- Check if the given charset is known to mnogosearch
udm_check_stored -- Check connection to stored
udm_clear_search_limits -- Clear all mnoGoSearch search restrictions
udm_close_stored -- Close connection to stored
udm_crc32 -- Return CRC32 checksum of given string
udm_errno -- Get mnoGoSearch error number
udm_error -- Get mnoGoSearch error message
udm_find -- Perform search
udm_free_agent -- Free mnoGoSearch session
udm_free_ispell_data -- Free memory allocated for ispell data
udm_free_res -- Free mnoGoSearch result
udm_get_doc_count -- Get total number of documents in database
udm_get_res_field -- Fetch mnoGoSearch result field
udm_get_res_param -- Get mnoGoSearch result parameters
udm_hash32 -- Return Hash32 checksum of gived string
udm_load_ispell_data -- Load ispell data
udm_open_stored -- Open connection to stored
udm_set_agent_param -- Set mnoGoSearch agent session parameters

udm_add_search_limit

(PHP 4 >= 4.0.5, PHP 5 <= 5.0.4)

udm_add_search_limit -- Add various search limits

Description

bool udm_add_search_limit ( resource agent, int var, string val )

udm_add_search_limit() adds search restrictions. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

agent - a link to Agent, received after call to udm_alloc_agent().

var - defines parameter, indicating limit.

val - defines the value of the current parameter.

Possible var values:

UDM_LIMIT_URL - defines document URL limitations to limit the search through subsection of the database. It supports SQL % and _ LIKE wildcards, where % matches any number of characters, even zero characters, and _ matches exactly one character. E.g. http://www.example.___/catalog may stand for http://www.example.com/catalog and http://www.example.net/catalog.
UDM_LIMIT_TAG - defines site TAG limitations. In indexer-conf you can assign specific TAGs to various sites and parts of a site. Tags in mnoGoSearch 3.1.x are lines, that may contain metasymbols % and _. Metasymbols allow searching among groups of tags. E.g. there are links with tags ABCD and ABCE, and search restriction is by ABC_ - the search will be made among both of the tags.
UDM_LIMIT_LANG - defines document language limitations.
UDM_LIMIT_CAT - defines document category limitations. Categories are similar to tag feature, but nested. So you can have one category inside another and so on. You have to use two characters for each level. Use a hex number going from 0-F or a 36 base number going from 0-Z. Therefore a top-level category like 'Auto' would be 01. If it has a subcategory like 'Ford', then it would be 01 (the parent category) and then 'Ford' which we will give 01. Put those together and you get 0101. If 'Auto' had another subcategory named 'VW', then it's id would be 01 because it belongs to the 'Ford' category and then 02 because it's the next category. So it's id would be 0102. If VW had a sub category called 'Engine' then it's id would start at 01 again and it would get the 'VW' id 02 and 'Auto' id of 01, making it 010201. If you want to search for sites under that category then you pass it cat=010201 in the URL.
UDM_LIMIT_DATE - defines limitation by date the document was modified.
Format of parameter value: a string with first character < or >, then with no space - date in unixtime format, for example:
Esempio 1.
<?php Udm_Add_Search_Limit($udm, UDM_LIMIT_DATE, "<908012006"); ?>
If > character is used, then the search will be restricted to those documents having a modification date greater than entered, if <, then smaller.

udm_alloc_agent_array

(PHP 4 >= 4.3.3, PHP 5 <= 5.0.4)

udm_alloc_agent_array -- Allocate mnoGoSearch session

Description

resource udm_alloc_agent_array ( array databases )

udm_alloc_agent_array() will create an agent with multiple database connections. The array databases must contain one database URL per element, analog to the first parameter of udm_alloc_agent().

udm_alloc_agent

(PHP 4 >= 4.0.5, PHP 5 <= 5.0.4)

udm_alloc_agent -- Allocate mnoGoSearch session

Description

resource udm_alloc_agent ( string dbaddr [, string dbmode] )

Returns a mnogosearch agent identifier on success, FALSE on failure. This function creates a session with database parameters.

dbaddr - URL-style database description, with options (type, host, database name, port, user and password) to connect to SQL database. Do not matter for built-in text files support. Format for dbaddr: DBType:[//[DBUser[:DBPass]@]DBHost[:DBPort]]/DBName/. Currently supported DBType values are: mysql, pgsql, msql, solid, mssql, oracle, and ibase. Actually, it does not matter for native libraries support, but ODBC users should specify one of the supported values. If your database type is not supported, you may use unknown instead.

dbmode - You may select the SQL database mode of words storage. Possible values of dbmode are: single, multi, crc, or crc-multi. When single is specified, all words are stored in the same table. If multi is selected, words will be located in different tables depending of their lengths. "multi" mode is usually faster, but requires more tables in the database. If "crc" mode is selected, mnoGoSearch will store 32 bit integer word IDs calculated by CRC32 algorithm instead of words. This mode requires less disk space and it is faster comparing with "single" and "multi" modes. crc-multi uses the same storage structure with the "crc" mode, but also stores words in different tables depending on words lengths like in "multi" mode.

Nota: dbaddr and dbmode must match those used during indexing.

Nota: In fact this function does not open a connection to the database and thus does not check the entered login and password. Establishing a connection to the database and login/password verification is done by udm_find().

udm_api_version

(PHP 4 >= 4.0.5, PHP 5 <= 5.0.4)

udm_api_version -- Get mnoGoSearch API version

Description

int udm_api_version ( void )

udm_api_version() returns the mnoGoSearch API version number. E.g. if mnoGoSearch 3.1.10 API is used, this function will return 30110.

This function allows the user to identify which API functions are available, e.g. udm_get_doc_count() function is only available in mnoGoSearch 3.1.11 or later.

Esempio 1. udm_api_version() example

<?php
if (udm_api_version() >= 30111) {
    echo  "Total number of URLs in database: " . udm_get_doc_count($udm) . "<br />\n";
}
?>

udm_cat_list

(PHP 4 >= 4.0.6, PHP 5 <= 5.0.4)

udm_cat_list -- Get all the categories on the same level with the current one

Description

array udm_cat_list ( resource agent, string category )

Returns an array listing all categories of the same level as the current category in the categories tree. agent is the agent identifier returned by a previous call to >udm_alloc_agent().

The function can be useful for developing categories tree browser.

The returned array consists of pairs. Elements with even index numbers contain the category paths, odd elements contain the corresponding category names.

$array[0] will contain '020300'
  $array[1] will contain 'Audi'
  $array[2] will contain '020301'
  $array[3] will contain 'BMW'
  $array[4] will contain '020302'
  $array[5] will contain 'Opel'
  ...
 etc.

Following is an example of displaying links of the current level in format:
Audi BMW Opel ...

Esempio 1. udm_cat_list()example
<?php $cat_list_arr = udm_cat_list($udm_agent, $cat); $cat_list = ''; for ($i=0; $i<count($cat_list_arr); $i+=2) { $path = $cat_list_arr[$i]; $name = $cat_list_arr[$i+1]; $cat_list .= "<a href=\"$_SERVER[PHP_SELF]?cat=$path\">$name</a><br />"; } ?>

udm_cat_path

(PHP 4 >= 4.0.6, PHP 5 <= 5.0.4)

udm_cat_path -- Get the path to the current category

Description

array udm_cat_path ( resource agent, string category )

Returns an array describing the path in the categories tree from the tree root to the current one, specified by category. agent is the agent identifier returned by a previous call to >udm_alloc_agent().

udm_errno() returns mnoGoSearch error number, zero if no error.

agent - link to agent identifier, received after call to udm_alloc_agent().

Receiving numeric agent error code.

udm_error

(PHP 4 >= 4.0.5, PHP 5 <= 5.0.4)

udm_error -- Get mnoGoSearch error message

Description

string udm_error ( resource agent )

udm_error() returns mnoGoSearch error message, empty string if no error.

agent - link to agent identifier, received after call to udm_alloc_agent().

Receiving agent error message.

udm_find

(PHP 4 >= 4.0.5, PHP 5 <= 5.0.4)

udm_find -- Perform search

Description

resource udm_find ( resource agent, string query )

Returns a result link identifier on success, or FALSE on failure.

The search itself. The first argument - session, the next one - query itself. To find something just type words you want to find and press SUBMIT button. For example, "mysql odbc". You should not use quotes " in query, they are written here only to divide a query from other text. mnoGoSearch will find all documents that contain word "mysql" and/or word "odbc". Best documents having bigger weights will be displayed first. If you use search mode ALL, search will return documents that contain both (or more) words you entered. In case you use mode ANY, the search will return list of documents that contain any of the words you entered. If you want more advanced results you may use query language. You should select "bool" match mode in the search from.

mnoGoSearch understands the following boolean operators:

string udm_get_res_field ( resource res, int row, int field )

udm_get_res_field() returns result field value on success, FALSE on error.

res - a link to result identifier, received after call to udm_find().

row - the number of the link on the current page. May have values from 0 to UDM_PARAM_NUM_ROWS-1.

field - field identifier, may have the following values:

UDM_FIELD_URL - document URL field
UDM_FIELD_CONTENT - document Content-type field (for example, text/html).
UDM_FIELD_CATEGORY - document category field. Use udm_cat_path() to get full path to current category from the categories tree root. (This parameter is available only in PHP 4.0.6 or later).
UDM_FIELD_TITLE - document title field.
UDM_FIELD_KEYWORDS - document keywords field (from META KEYWORDS tag).
UDM_FIELD_DESC - document description field (from META DESCRIPTION tag).
UDM_FIELD_TEXT - document body text (the first couple of lines to give an idea of what the document is about).
UDM_FIELD_SIZE - document size.
UDM_FIELD_URLID - unique URL ID of the link.
UDM_FIELD_RATING - page rating (as calculated by mnoGoSearch).
UDM_FIELD_MODIFIED - last-modified field in unixtime format.
UDM_FIELD_ORDER - the number of the current document in set of found documents.
UDM_FIELD_CRC - document CRC.

udm_get_res_param

(PHP 4 >= 4.0.5, PHP 5 <= 5.0.4)

udm_get_res_param -- Get mnoGoSearch result parameters

Description

string udm_get_res_param ( resource res, int param )

udm_get_res_param() returns result parameter value on success, FALSE on error.

res - a link to result identifier, received after call to udm_find().

param - parameter identifier, may have the following values:

UDM_PARAM_NUM_ROWS - number of received found links on the current page. It is equal to UDM_PARAM_PAGE_SIZE for all search pages, on the last page - the rest of links.
UDM_PARAM_FOUND - total number of results matching the query.
UDM_PARAM_WORDINFO - information on the words found. E.g. search for "a good book" will return "a: stopword, good:5637, book: 120"
UDM_PARAM_SEARCHTIME - search time in seconds.
UDM_PARAM_FIRST_DOC - the number of the first document displayed on current page.
UDM_PARAM_LAST_DOC - the number of the last document displayed on current page.

udm_hash32

(PHP 4 >= 4.3.3, PHP 5 <= 5.0.4)

udm_hash32 -- Return Hash32 checksum of gived string

Description

int udm_hash32 ( resource agent, string str )

udm_hash32() will take a string str and return a quite unique 32-bit hash number from it. Requires an allocated agent.

udm_load_ispell_data

(PHP 4 >= 4.0.5, PHP 5 <= 5.0.4)

udm_load_ispell_data -- Load ispell data

Description

bool udm_load_ispell_data ( resource agent, int var, string val1, string val2, int flag )

udm_load_ispell_data() loads ispell data. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

agent - agent link identifier, received after call to udm_alloc_agent().

var - parameter, indicating the source for ispell data. May have the following values:

After using this function to free memory allocated for ispell data, please use udm_free_ispell_data(), even if you use UDM_ISPELL_TYPE_SERVER mode.

The fastest mode is UDM_ISPELL_TYPE_SERVER. UDM_ISPELL_TYPE_TEXT is slower and UDM_ISPELL_TYPE_DB is the slowest. The above pattern is TRUE for mnoGoSearch 3.1.10 - 3.1.11. It is planned to speed up DB mode in future versions and it is going to be faster than TEXT mode.

UDM_ISPELL_TYPE_DB - indicates that ispell data should be loaded from SQL. In this case, parameters val1 and val2 are ignored and should be left blank. flag should be equal to 1.
Nota: flag indicates that after loading ispell data from defined source it should be sorted (it is necessary for correct functioning of ispell). In case of loading ispell data from files there may be several calls to udm_load_ispell_data(), and there is no sense to sort data after every call, but only after the last one. Since in db mode all the data is loaded by one call, this parameter should have the value 1. In this mode in case of error, e.g. if ispell tables are absent, the function will return FALSE and code and error message will be accessible through udm_error() and udm_errno().
Esempio 1. udm_load_ispell_data()example
<?php if (! udm_load_ispell_data($udm, UDM_ISPELL_TYPE_DB, '', '', 1)) { printf("Error #%d: '%s'\n", udm_errno($udm), udm_error($udm)); exit; } ?>

UDM_ISPELL_TYPE_AFFIX - indicates that ispell data should be loaded from file and initiates loading affixes file. In this case val1 defines double letter language code for which affixes are loaded, and val2 - file path. Please note, that if a relative path entered, the module looks for the file not in UDM_CONF_DIR, but in relation to current path, i.e. to the path where the script is executed. In case of error in this mode, e.g. if file is absent, the function will return FALSE, and an error message will be displayed. Error message text cannot be accessed through udm_error() and udm_errno(), since those functions can only return messages associated with SQL. Please, see flag parameter description in UDM_ISPELL_TYPE_DB.

Esempio 2. udm_load_ispell_data() example
<?php if ((! udm_load_ispell_data($udm, UDM_ISPELL_TYPE_AFFIX, 'en', '/opt/ispell/en.aff', 0)) || (! udm_load_ispell_data($udm, UDM_ISPELL_TYPE_AFFIX, 'ru', '/opt/ispell/ru.aff', 0)) || (! udm_load_ispell_data($udm, UDM_ISPELL_TYPE_SPELL, 'en', '/opt/ispell/en.dict', 0)) || (! udm_load_ispell_data($udm, UDM_ISPELL_TYPE_SPELL, 'ru', '/opt/ispell/ru.dict', 1))) { exit; } ?>

Nota: flag is equal to 1 only in the last call.

UDM_ISPELL_TYPE_SPELL - indicates that ispell data should be loaded from file and initiates loading of ispell dictionary file. In this case val1 defines double letter language code for which affixes are loaded, and val2 - file path. Please note, that if a relative path entered, the module looks for the file not in UDM_CONF_DIR, but in relation to current path, i.e. to the path where the script is executed. In case of error in this mode, e.g. if file is absent, the function will return FALSE, and an error message will be displayed. Error message text cannot be accessed through udm_error() and udm_errno(), since those functions can only return messages associated with SQL. Please, see flag parameter description in UDM_ISPELL_TYPE_DB.

<?php
     if ((! Udm_Load_Ispell_Data($udm, UDM_ISPELL_TYPE_AFFIX, 'en', '/opt/ispell/en.aff', 0)) ||
        (! Udm_Load_Ispell_Data($udm, UDM_ISPELL_TYPE_AFFIX, 'ru', '/opt/ispell/ru.aff', 0)) ||
        (! Udm_Load_Ispell_Data($udm, UDM_ISPELL_TYPE_SPELL, 'en', '/opt/ispell/en.dict', 0)) ||
        (! Udm_Load_Ispell_Data($udm, UDM_ISPELL_TYPE_SPELL, 'ru', '/opt/ispell/ru.dict', 1))) {
      exit;
      }
?>

Nota: flag is equal to 1 only in the last call.

UDM_ISPELL_TYPE_SERVER - enables spell server support. val1 parameter indicates address of the host running spell server. val2 ` is not used yet, but in future releases it is going to indicate number of port used by spell server. flag parameter in this case is not needed since ispell data is stored on spellserver already sorted.
Spelld server reads spell-data from a separate configuration file (/usr/local/mnogosearch/etc/spelld.conf by default), sorts it and stores in memory. With clients server communicates in two ways: to indexer all the data is transferred (so that indexer starts faster), from search.cgi server receives word to normalize and then passes over to client (search.cgi) list of normalized word forms. This allows fastest, compared to db and text modes processing of search queries (by omitting loading and sorting all the spell data).
udm_load_ispell_data() function in UDM_ISPELL_TYPE_SERVER mode does not actually load ispell data, but only defines server address. In fact, server is automatically used by udm_find() function when performing search. In case of errors, e.g. if spellserver is not running or invalid host indicated, there are no messages returned and ispell conversion does not work.
Nota: This function is available in mnoGoSearch 3.1.12 or later.
Example:
<?php if (!udm_load_ispell_data($udm, UDM_ISPELL_TYPE_SERVER, '', '', 1)) { echo "Error loading ispell data from server<br />\n"; exit; } ?>

udm_open_stored

(PHP 4 >= 4.2.0)

udm_open_stored -- Open connection to stored

Description

int udm_open_stored ( resource agent, string storedaddr )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

udm_set_agent_param

(PHP 4 >= 4.0.5, PHP 5 <= 5.0.4)

udm_set_agent_param -- Set mnoGoSearch agent session parameters

Description

bool udm_set_agent_param ( resource agent, int var, string val )

Restituisce TRUE in caso di successo, FALSE in caso di fallimento. Defines mnoGoSearch session parameters.

The following parameters and their values are available:

UDM_PARAM_PAGE_NUM - used to choose search results page number (results are returned by pages beginning from 0, with UDM_PARAM_PAGE_SIZE results per page).
UDM_PARAM_PAGE_SIZE - number of search results displayed on one page.
UDM_PARAM_SEARCH_MODE - search mode. The following values available: UDM_MODE_ALL - search for all words; UDM_MODE_ANY - search for any word; UDM_MODE_PHRASE - phrase search; UDM_MODE_BOOL - boolean search. See udm_find() for details on boolean search.
UDM_PARAM_CACHE_MODE - turns on or off search result cache mode. When enabled, the search engine will store search results to disk. In case a similar search is performed later, the engine will take results from the cache for faster performance. Available values: UDM_CACHE_ENABLED, UDM_CACHE_DISABLED.
UDM_PARAM_TRACK_MODE - turns on or off trackquery mode. Since version 3.1.2 mnoGoSearch has a query tracking support. Note that tracking is implemented in SQL version only and not available in built-in database. To use tracking, you have to create tables for tracking support. For MySQL, use create/mysql/track.txt. When doing a search, front-end uses those tables to store query words, a number of found documents and current Unix timestamp in seconds. Available values: UDM_TRACK_ENABLED, UDM_TRACK_DISABLED.
UDM_PARAM_PHRASE_MODE - defines whether index database using phrases ("phrase" parameter in indexer.conf). Possible values: UDM_PHRASE_ENABLED and UDM_PHRASE_DISABLED. Please note, that if phrase search is enabled (UDM_PHRASE_ENABLED), it is still possible to do search in any mode (ANY, ALL, BOOL or PHRASE). In 3.1.10 version of mnoGoSearch phrase search is supported only in sql and built-in database modes, while beginning with 3.1.11 phrases are supported in cachemode as well.
Examples of phrase search:
"Arizona desert" - This query returns all indexed documents that contain "Arizona desert" as a phrase. Notice that you need to put double quotes around the phrase
UDM_PARAM_CHARSET - defines local charset. Available values: set of charsets supported by mnoGoSearch, e.g. koi8-r, cp1251, ...
UDM_PARAM_STOPFILE - Defines name and path to stopwords file. (There is a small difference with mnoGoSearch - while in mnoGoSearch if relative path or no path entered, it looks for this file in relation to UDM_CONF_DIR, the module looks for the file in relation to current path, i.e. to the path where the PHP script is executed.)
UDM_PARAM_STOPTABLE - Load stop words from the given SQL table. You may use several StopwordTable commands. This command has no effect when compiled without SQL database support.
UDM_PARAM_WEIGHT_FACTOR - represents weight factors for specific document parts. Currently body, title, keywords, description, url are supported. To activate this feature please use degrees of 2 in *Weight commands of the indexer.conf. Let's imagine that we have these weights:

  URLWeight     1
  BodyWeight    2
  TitleWeight   4
  KeywordWeight 8
  DescWeight    16

As far as indexer uses bit OR operation for word weights when some word presents several time in the same document, it is possible at search time to detect word appearance in different document parts. Word which appears only in the body will have 00000010 aggregate weight (in binary notation). Word used in all document parts will have 00011111 aggregate weight.
This parameter's value is a string of hex digits ABCDE. Each digit is a factor for corresponding bit in word weight. For the given above weights configuration:

   E is a factor for weight 1  (URL Weight bit)
   D is a factor for weight 2  (BodyWeight bit)
   C is a factor for weight 4  (TitleWeight bit)
   B is a factor for weight 8  (KeywordWeight bit)
   A is a factor for weight 16 (DescWeight bit)

Examples:
UDM_PARAM_WEIGHT_FACTOR=00001 will search through URLs only.
UDM_PARAM_WEIGHT_FACTOR=00100 will search through Titles only.
UDM_PARAM_WEIGHT_FACTOR=11100 will search through Title,Keywords,Description but not through URL and Body.
UDM_PARAM_WEIGHT_FACTOR=F9421 will search through:

    Description with factor 15  (F hex)
    Keywords with factor 9
    Title with factor  4
    Body with factor 2
    URL with factor 1

If UDM_PARAM_WEIGHT_FACTOR variable is omitted, original weight value is taken to sort results. For a given above weight configuration it means that document description has a most big weight 16.
UDM_PARAM_WORD_MATCH - word match. You may use this parameter to choose word match type. This feature works only in "single" and "multi" modes using SQL based and built-in database. It does not work in cachemode and other modes since they use word CRC and do not support substring search. Available values:
UDM_MATCH_BEGIN - word beginning match;
UDM_MATCH_END - word ending match;
UDM_MATCH_WORD - whole word match;
UDM_MATCH_SUBSTR - word substring match.
UDM_PARAM_MIN_WORD_LEN - defines minimal word length. Any word shorter this limit is considered to be a stopword. Please note that this parameter value is inclusive, i.e. if UDM_PARAM_MIN_WORD_LEN=3, a word 3 characters long will not be considered a stopword, while a word 2 characters long will be. Default value is 1.
UDM_PARAM_ISPELL_PREFIXES - Possible values: UDM_PREFIXES_ENABLED and UDM_PREFIXES_DISABLED, that respectively enable or disable using prefixes. E.g. if a word "tested" is in search query, also words like "test", "testing", etc. Only suffixes are supported by default. Prefixes usually change word meanings, for example if somebody is searching for the word "tested" one hardly wants "untested" to be found. Prefixes support may also be found useful for site's spelling checking purposes. In order to enable ispell, you have to load ispell data with udm_load_ispell_data().
UDM_PARAM_CROSS_WORDS - enables or disables crosswords support. Possible values: UDM_CROSS_WORDS_ENABLED and UDM_CROSS_WORDS_DISABLED.
The crosswords feature allows to assign words between <a href="xxx"> and </a> also to a document this link leads to. It works in SQL database mode and is not supported in built-in database and Cachemode.
Nota: Crosswords are supported only in mnoGoSearch 3.1.11 or later.
UDM_PARAM_VARDIR - specifies a custom path to directory where indexer stores data when using built-in database and in cache mode. By default /var directory of mnoGoSearch installation is used. Can have only string values. The parameter is available in PHP 4.1.0 or later.

LXXX. Funzioni per Microsoft SQL Server

Introduzione

Queste funzioni permettono di accedere ad un database MS SQL Server.

Requisiti

Requisiti per le piattaforme Win32

Per potere funzionare è richiesto che sia installato il MS SQL Client Tools sullo stesso sistema su cui è il installato il PHP. Il Client Tools può essere installato o dal cd di MS SQL Server, o copiando il file ntwdblib.dll dalla directory \winnt\system32 del server alla directory \winnt\system32 della macchina su cui è installato il PHP. La copia del file ntwdblib.dll permette solo l'accesso al database. La configurazione del client richiede comunque l'installazione di tutto il pacchetto MS SQL Client Tools.

Requisiti per le piattaforme Unix/Linux

Per potere utilizzare l'estensione MSSQl su piattaforme Unix/Linux, occorre compilare ed installare la libreria FreeTDS. Il codice sorgente e le istruzioni per l'installazione sono disponibili nel sito di FreeTDS: http://www.freetds.org/

Nota: Nella piattaforma Windows si utilizzano le DBLIB di Microsoft. Quindi le funzioni che restituiscono il nome della colonna si basano sulla funzione dbcolname() della DBLIB. La DBLIB è stata sviluppata per SQL Server 6.x che ammetteva nomi di colonna lunghi al massimo 30 caratteri. Per questo motivo il numero massimo di caratteri per il nome colonna ammessi sono 30. Nelle piattaforme in cui si utilizza FreeTDS (Linux) non si ha questo problema.

Installazione

Il modulo MSSQL si abilita aggiungendo extension=php_mssql.dll al file di configurazione php.ini.

Per attivare queste funzionalità occorre compilare il PHP con --with-mssql[=DIR], dove DIR è la directory in cui è installato FreeTDS. Il pacchetto FreeTDS dovrebbe essere compilato utilizzando --enable-msdblib.

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

Tabella 1. Parametri di configurazione per il modulo MS SQL Server

Nome	Default	Modificabile	Log Variazioni
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	Disponibile da PHP 4.1.0
mssql.textsize	"-1"	PHP_INI_ALL
mssql.textlimit	"-1"	PHP_INI_ALL
mssql.batchsize	"0"	PHP_INI_ALL	Disponibile da PHP 4.0.4
mssql.datetimeconvert	"1"	PHP_INI_ALL	Disponibile da PHP 4.2.0
mssql.secure_connection	"0"	PHP_INI_SYSTEM	Disponibile da PHP 4.3.0
mssql.max_procs	"25"	PHP_INI_ALL	Disponibile da PHP 4.3.0

Per maggiori dettagli sulle costanti PHP_INI_* vedere Appendice G.

Tipi di risorse

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

MSSQL_ASSOC (integer)
MSSQL_NUM (integer)
MSSQL_BOTH (integer)
SQLTEXT (integer)
SQLVARCHAR (integer)
SQLCHAR (integer)
SQLINT1 (integer)
SQLINT2 (integer)
SQLINT4 (integer)
SQLBIT (integer)
SQLFLT8 (integer)

Sommario
mssql_bind -- Aggiunge un parametro ad una procedura memorizzata (stored procedure) locale o remota
mssql_close -- Chiude la connessione con MS SQL Server
mssql_connect -- Apre una connessione con un server MS SQL
mssql_data_seek -- Sposta il puntatore di riga interno
mssql_execute -- Esegue una procedura memorizzata su un database MS SQL
mssql_fetch_array -- Restituisce una riga in un array associativo, numerico o entrambi
mssql_fetch_assoc -- Restituisce un array associativo con i dati di una riga dal set di risultati indicato da id_risultato
mssql_fetch_batch -- Restituisce il successivo gruppo di record
mssql_fetch_field -- Restituisce le informazioni di un campo
mssql_fetch_object -- Restituisce una riga come oggetto
mssql_fetch_row -- Restituisce una riga come array numerato
mssql_field_length -- Restituisce la lunghezza di un campo
mssql_field_name -- Restituisce il nome di un campo
mssql_field_seek -- Ricerca il campo con l'offset specificato
mssql_field_type -- Restituisce il tipo di un campo
mssql_free_result -- Libera la memoria di un risultato
mssql_free_statement -- Free statement memory
mssql_get_last_message -- Restituisce l'ultimo messaggio dal server
mssql_guid_string -- Converte il GUID dal formato binario a 16 bit al formato stringa
mssql_init -- Inizializza una procedura memorizata locale o remota
mssql_min_error_severity -- Setta il livello minimo di errori critici.
mssql_min_message_severity -- Setta li livello critico minimo di messaggi
mssql_next_result -- Muove il puntatore interno al risultato successivo
mssql_num_fields -- Restituisce il numero di campi in un risultato
mssql_num_rows -- Restituisce il numero di righe
mssql_pconnect -- Apre una connessione persistente con MS SQL
mssql_query -- Invia una query a MS SQL
mssql_result -- Restituisce i dati di un risultato
mssql_rows_affected -- Restituisce il numero di record coinvolti dalla query
mssql_select_db -- Seleziona un database MS SQL

mssql_bind

(PHP 4 >= 4.1.0, PHP 5)

bool mssql_data_seek ( resource id_risultato, int numero_riga )

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

La funzione mssql_data_seek() sposta il puntatore di riga, interno al risultato associato all'identificativo di risultato, alla riga indicata dall'argomento numero_riga, la prima riga inzia con il numero 0. La chiamata successiva a mssql_fetch_row() restituirà la riga richiesta.

mssql_execute

(PHP 4 >= 4.1.0, PHP 5)

mssql_execute -- Esegue una procedura memorizzata su un database MS SQL

Descrizione

mixed mssql_execute ( resource stmt [, bool skip_results] )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Nota: Se le stored procedure restituiscono parametri oppure valori, questi saranno disponibili successivamente all'esecuzione della funzione mssql_execute() a meno che non sia restituito più di un set di risultati. In questo caso occorre utilizzare mssql_next_result() per spostarsi tra i risultati. Una volta terminato lo scorrimento dei set di risultati, sia i parametri di output sia i valori di ritorno saranno disponibili.

Vedere anche mssql_bind(), mssql_free_statement() e mssql_init().

mssql_fetch_array

(PHP 3, PHP 4, PHP 5)

mssql_fetch_array -- Restituisce una riga in un array associativo, numerico o entrambi

Descrizione

array mssql_fetch_array ( resource id_risultato [, int tipo_array] )

La funzione restituisce: un array corrispondente alla riga estratta, oppure falso se non vi sono più righe.

La funzione mssql_fetch_array() è un' estensione della funzione mssql_fetch_row(). Oltre a memorizzare i dati in un array con indice numerico, la funzione memorizza i dati in un array associativo in cui la chiave è costituita dal nome del campo.

Un aspetto da notare è che la funzione mssql_fetch_array() NON è significativamente più lenta rispetto a mssql_fetch_row(), mentre nel contempo fornisce funzionalità maggiori.

Nota: I nomi dei campi restituiti da questa funzione sono case-sensitive.

Nota: This function sets NULL fields to PHP NULL value.

La funzione mssql_fetch_field() può essere utilizzata per ottenere informazioni sui campi presenti nel risultato di una certa query. Se non viene specificato l'argomento offset_campo, la funzione restituisce il campo successivo che non è ancora stato restituito da mssql_fetch_field().

Le proprietà dell'oggetto sono:

name - nome della colonna. Se la colonna è il risultato di una funzione, questa proprietà è valorizzata con "computed#N", dove #N è un numero progressivo.
column_source - tabella da cui sono ricavate le colonne
max_length - lunghezza massima della colonna
numeric - 1 se la colonna è numerica
type - tipo di colonna.

Vedere anche mssql_field_seek().

mssql_fetch_object

(PHP 3, PHP 4, PHP 5)

mssql_fetch_object -- Restituisce una riga come oggetto

Descrizione

object mssql_fetch_object ( resource id_risultato )

La funzione restituisce un oggetto le cui proprietà corrispondono alla riga estratta, oppure falso se non vi sono più righe.

La funzione mssql_fetch_object() è simile a mssql_fetch_array(), tranne che per una differenza, la prima restituisce un oggetto, la seconda un array. Indirettamente questo significa che si può accedere ai dati solo attraverso il nome dei campi e non tramite il loro offset (i numeri non sono dei validi nomi di proprietà).

Nota: I nomi dei campi restituiti da questa funzione sono case-sensitive.

Nota: This function sets NULL fields to PHP NULL value.

A livello di velocità il comportamento è simile a mssql_fetch_array(), e quasi veloce come mssql_fetch_row() (la differenza è insignificante ).

Vedere anche mssql_fetch_array() e mssql_fetch_row().

mssql_fetch_row

(PHP 3, PHP 4, PHP 5)

mssql_fetch_row -- Restituisce una riga come array numerato

Descrizione

array mssql_fetch_row ( resource id_risultato )

La funzione restituisce un array che corrisponde alla riga estratta, oppure falso se non vi sono più righe.

La funzione mssql_fetch_row() estrae una riga di dati dal risultato associato all'identificativo di risultato passato. La riga viene restituita in un array. Ciascuna colonna è memorizzata in un campo dell'array. Il primo ha indice 0.

Esecuzione successive di mssql_fetch_row() restituiscono le righe successive presenti nel risultato, oppure falso se non vi sono più righe.

Nota: This function sets NULL fields to PHP NULL value.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche mssql_fetch_field().

mssql_field_type

(PHP 3 >= 3.0.3, PHP 4, PHP 5)

mssql_field_type -- Restituisce il tipo di un campo

Descrizione

string mssql_field_type ( resource id_risultato [, int offset] )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

mssql_free_result

(PHP 3, PHP 4, PHP 5)

mssql_free_result -- Libera la memoria di un risultato

Descrizione

bool mssql_free_result ( resource id_risultato )

E' necessario l'utilizzo della funzione mssql_free_result() solo quando si è preoccupati dell'occupazione di memoria durante l'esecuzione dello script. Normalmente tutti i dati verranno rimossi automaticamente dalla memoria al termine dell'esecuzione dello script.E' tuttavia possibile eseguire mssql_free_result(), per liberare la memoria occupata dai dati indicati dal parametro id_risultato

mssql_free_statement

(PHP 4 >= 4.3.2, PHP 5)

mssql_free_statement -- Free statement memory

int mssql_init ( string sp_name [, resource id_connessione] )

bool mssql_next_result ( resource id_risultato )

Nel caso in cui si eseguano più di una istruzione SQL al server, oppure si eseguano delle procedure memorizzate (stored procedure) con possibilità di molteplici risultati, il server restituirà un set di diversi risultati. Questa funzione verifica se esistono ulteriori risultati dal server. Se effettivamente esiste un'altro risultato, questa funzione libera la memoria dal risultato corrente e si predispone per la ricezione del risultato successivo. La funzione restituisce TRUE se è disponibile un'altro risultato, FALSE in caso contrario.

Esempio 1. mssql_next_result() Esempio di utilizzo

<?php
    $link = mssql_connect("localhost", "utente", "password");
    mssql_select_db("MyDB", $link);
    $SQL = "Select * from tabella1 select * from tabella2";
    $rs = mssql_query($SQL, $link);
    do {
        while ($row = mssql_fetch_row($rs)) {
        }
    } while (mssql_next_result($rs));
    mssql_free_result($rs);
    mssql_close($link);
?>

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

mssql_select_db

(PHP 3, PHP 4, PHP 5)

mssql_select_db -- Seleziona un database MS SQL

Descrizione

bool mssql_select_db ( string Nome_database [, resource id_connessione] )

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

La funzione mssql_select_db() setta il database attivo sul server attraverso la connessione specificata da id_connessione. Se l'argomento id_connessione non viene fornito, si utilizza l'ultima connessione aperta in ordine di tempo. Se non vi sono connessioni aperte, la funzione tenta di stabilire una connessione, come se fosse utilizzata la funzione mssql_connect(), e utilizza quella.

Ciascuna esecuzione di mssql_query() sarà fatta sul database attivo.

Per potere selezionare un database contenente un nome o un trattivo ("-") nel nome occorre racchiudere il nome stesso tra parantesi quadre, come illustrato nell'esempio seguente:

Esempio 1. Esempio di mssql_select_db()

<?php
  $conn = mssql_connect('MYSQLSERVER', 'sa', 'password');
  mssql_select_db('[my data-base]', $conn);
?>

Vedere anche: mssql_connect(), mssql_pconnect(), e mssql_query()

LXXXI. Microsoft SQL Server and Sybase Functions (PDO_DBLIB)

Introduzione

Avvertimento

PDO_DBLIB is a driver that implements the PHP Data Objects (PDO) interface to enable access from PHP to Microsoft SQL Server and Sybase databases through the FreeTDS libary.

On Windows, you should 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.

Sommario
PDO_DBLIB DSN -- Connecting to Microsoft SQL Server and Sybase databases

PDO_DBLIB DSN

(no version information, might be only in CVS)

PDO_DBLIB DSN -- Connecting to Microsoft SQL Server and Sybase databases

Descrizione

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 FreeTDS libraries, mssql: if PDO_DBLIB was linked against the Microsoft SQL Server libraries, or dblib: if linked against any other variety of DB-lib.
host: The hostname on which the database server resides.
dbname: The name of the database.

Esempi

Esempio 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

LXXXII. Mohawk Software Session Handler Functions

Introduzione

msession is an interface to a high speed session daemon which can run either locally or remotely. It is designed to provide consistent session management for a PHP web farm. More Information about msession and the session server software itself can be found at http://devel.mohawksoft.com/msession.html.

Nota: Questo modulo non è disponibile su piattaforme Windows.

Requisiti

Installazione

To enable Msession support configure PHP --with-msession[=DIR], where DIR is the Msession install directory.

Configurazione di Runtime

Tipi di risorse

Costanti predefinite

Sommario
msession_connect -- Connect to msession server
msession_count -- Get session count
msession_create -- Create a session
msession_destroy -- Destroy a session
msession_disconnect -- Close connection to msession server
msession_find -- Find all sessions with name and value
msession_get_array -- Get array of msession variables
msession_get_data -- Get data session unstructured data
msession_get -- Get value from session
msession_inc -- Increment value in session
msession_list -- List all sessions
msession_listvar -- List sessions with variable
msession_lock -- Lock a session
msession_plugin -- Call an escape function within the msession personality plugin
msession_randstr -- Get random string
msession_set_array -- Set msession variables from an array
msession_set_data -- Set data session unstructured data
msession_set -- Set value in session
msession_timeout -- Set/get session timeout
msession_uniq -- Get unique id
msession_unlock -- Unlock a session

LXXXIII. mSQL Functions

Introduzione

These functions allow you to access mSQL database servers. More information about mSQL can be found at http://www.hughes.com.au/.

Installazione

In order to have these functions available, you must compile PHP with msql support by using the --with-msql[=DIR] option. DIR is the mSQL base install directory, defaults to /usr/local/msql3.

Note to Win32 Users: In order to enable this module on a Windows environment, you must copy msql.dll from the DLL folder of the PHP/Win32 binary package to the SYSTEM32 folder of your windows machine. (Ex: C:\WINNT\SYSTEM32 or C:\WINDOWS\SYSTEM32)

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

Tabella 1. mSQL configuration options

Name	Default	Changeable
msql.allow_persistent	"1"	PHP_INI_ALL
msql.max_persistent	"-1"	PHP_INI_ALL
msql.max_links	"-1"	PHP_INI_ALL

Per maggiori dettagli sulle costanti PHP_INI_* vedere Appendice G.

Breve descrizione dei parametri di configurazione.

msql.allow_persistent boolean: Whether to allow persistent mSQL connections.
msql.max_persistent integer: The maximum number of persistent mSQL connections per process.
msql.max_links integer: The maximum number of mSQL connections per process, including persistent connections.

Tipi di risorse

There are two resource types used in the mSQL module. The first one is the link identifier for a database connection, the second a resource which holds the result of a query.

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

MSQL_ASSOC (integer)
MSQL_NUM (integer)
MSQL_BOTH (integer)

Esempi

This simple example shows how to connect, execute a query, print resulting rows and disconnect from a mSQL database.
Esempio 1. mSQL usage example
<?php /* Connecting, selecting database */ $link = msql_connect('localhost', 'username', 'password') or die('Could not connect : ' . msql_error($link)); msql_select_db('database', $link) or die('Could not select database'); /* Issue SQL query */ $query = 'SELECT * FROM my_table'; $result = msql_query($query, $link) or die('Query failed : ' . msql_error($link)); /* Printing results in 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"; /* Free result set */ msql_free_result($result); /* Close connection */ msql_close($link); ?>

Sommario
msql_affected_rows -- Returns number of affected rows
msql_close -- Close mSQL connection
msql_connect -- Open mSQL connection
msql_create_db -- Create mSQL database
msql_createdb -- Alias di msql_create_db()
msql_data_seek -- Move internal row pointer
msql_db_query -- Send mSQL query
msql_dbname -- Alias di msql_result()
msql_drop_db -- Drop (delete) mSQL database
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 of msql_field_flags()
msql_fieldlen -- Alias of msql_field_len()
msql_fieldname -- Alias of msql_field_name()
msql_fieldtable -- Alias of msql_field_table()
msql_fieldtype -- Alias of 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 of msql_num_fields()
msql_numrows -- Alias of msql_num_rows()
msql_pconnect -- Open persistent mSQL connection
msql_query -- Send mSQL query
msql_regcase -- Alias of sql_regcase()
msql_result -- Get result data
msql_select_db -- Select mSQL database
msql_tablename -- Alias of msql_result()
msql -- Alias of msql_db_query()

msql_affected_rows

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

msql_affected_rows -- Returns number of affected rows

Descrizione

int msql_affected_rows ( resource result )

Returns number of affected rows by the last SELECT, UPDATE or DELETE query associated with result.

Elenco dei parametri

result: The result resource that is being evaluated. This result comes from a call to msql_query().

Valori restituiti

Returns the number of affected rows on success, or FALSE on error.

Vedere anche:

msql_close

(PHP 3, PHP 4, PHP 5)

msql_close -- Close mSQL connection

Descrizione

bool msql_close ( [resource link_identifier] )

msql_close() closes the non-persistent connection to the mSQL server that's associated with the specified link identifier.

Using msql_close() isn't usually necessary, as non-persistent open links are automatically closed at the end of the script's execution. See also freeing resources.

Elenco dei parametri

link_identifier: The mSQL connection. If not specified, the last link opened by msql_connect() is assumed. If no such link is found, the function will try to establish a link as if msql_connect() was called, and use it.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

msql_pconnect()

msql_connect

(PHP 3, PHP 4, PHP 5)

msql_connect -- Open mSQL connection

Descrizione

resource msql_connect ( [string hostname] )

msql_connect() establishes a connection to a mSQL server.

In case a second call is made to msql_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 msql_close().

Elenco dei parametri

hostname

The hostname can also include a port number. e.g. hostname,port.

If not specified, the connection is established by the means of a Unix domain socket, being then more efficient then a localhost TCP socket connection.

Nota: While this function will accept a colon (:) as a host/port separator, a comma (,) is the preferred method.

Valori restituiti

Returns a positive mSQL link identifier on success, or FALSE on error.

Vedere anche:

msql_pconnect()

msql_close()

msql_create_db

(PHP 3, PHP 4, PHP 5)

msql_create_db -- Create mSQL database

Descrizione

bool msql_create_db ( string database_name [, resource link_identifier] )

msql_create_db() attempts to create a new database on the mSQL server.

Elenco dei parametri

database_name: The name of the mSQL database.
link_identifier: The mSQL connection. If not specified, the last link opened by msql_connect() is assumed. If no such link is found, the function will try to establish a link as if msql_connect() was called, and use it.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

msql_drop_db()

msql_createdb

(PHP 3, PHP 4, PHP 5)

msql_createdb -- Alias di msql_create_db()

Descrizione

This function is an alias of: msql_create_db().

msql_data_seek

(PHP 3, PHP 4, PHP 5)

msql_data_seek -- Move internal row pointer

Descrizione

bool msql_data_seek ( resource 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.

Elenco dei parametri

result: The result resource that is being evaluated. This result comes from a call to msql_query().
row_number: The seeked row number.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

msql_fetch_array()

msql_fetch_object()

msql_fetch_row()

msql_db_query

(PHP 3, PHP 4, PHP 5)

msql_db_query -- Send mSQL query

Descrizione

resource msql_db_query ( string database, string query [, resource link_identifier] )

msql_db_query() selects a database and executes a query on it.

Elenco dei parametri

database: The name of the mSQL database.
query: The SQL query.
link_identifier: The mSQL connection. If not specified, the last link opened by msql_connect() is assumed. If no such link is found, the function will try to establish a link as if msql_connect() was called, and use it.

Valori restituiti

Returns a positive mSQL query identifier to the query result, or FALSE on error.

Vedere anche:

msql_dbname

(PHP 3, PHP 4, PHP 5)

msql_dbname -- Alias di msql_result()

Descrizione

This function is an alias of: msql_result().

msql_drop_db

(PHP 3, PHP 4, PHP 5)

msql_drop_db -- Drop (delete) mSQL database

Descrizione

bool msql_drop_db ( string database_name [, resource link_identifier] )

msql_drop_db() attempts to drop (remove) a database from the mSQL server.

Elenco dei parametri

database_name: The name of the database.
link_identifier: The mSQL connection. If not specified, the last link opened by msql_connect() is assumed. If no such link is found, the function will try to establish a link as if msql_connect() was called, and use it.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

msql_create_db()

msql_error

(PHP 3, PHP 4, PHP 5)

msql_error -- Returns error message of last msql call

Descrizione

string msql_error ( void )

msql_error() returns the last issued error by the mSQL server. Note that only the last error message is accessible with msql_error().

Valori restituiti

The last error message or an empty string if no error was issued.

msql_fetch_array

(PHP 3, PHP 4, PHP 5)

msql_fetch_array -- Fetch row as array

Descrizione

array msql_fetch_array ( resource 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.

Elenco dei parametri

result: The result resource that is being evaluated. This result comes from a call to msql_query().
result_type: A constant that can take the following values: MSQL_ASSOC, MSQL_NUM, and MSQL_BOTH with MSQL_BOTH being the default.

Valori restituiti

Returns an array that corresponds to the fetched row, or FALSE if there are no more rows.

Esempi

Esempio 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); ?>

Log delle modifiche

Versione	Descrizione
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.

Vedere anche:

msql_fetch_row()

msql_fetch_object()

msql_data_seek()

msql_fetch_field

(PHP 3, PHP 4, PHP 5)

msql_fetch_field -- Get field information

Descrizione

object msql_fetch_field ( resource result [, int field_offset] )

msql_fetch_field() can be used in order to obtain information about fields in a certain query result.

Elenco dei parametri

result: The result resource that is being evaluated. This result comes from a call to msql_query().
field_offset: The field offset. If not specified, the next field that wasn't yet retrieved by msql_fetch_field() is retrieved.

Valori restituiti

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

Vedere anche:

msql_field_seek()

msql_fetch_object

(PHP 3, PHP 4, PHP 5)

msql_fetch_object -- Fetch row as object

Descrizione

object msql_fetch_object ( resource 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).

Elenco dei parametri

result: The result resource that is being evaluated. This result comes from a call to msql_query().

Valori restituiti

Returns an object with properties that correspond to the fetched row, or FALSE if there are no more rows.

Esempi

Esempio 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); ?>

Log delle modifiche

Versione	Descrizione
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.

Vedere anche:

msql_fetch_array()

msql_fetch_row()

msql_data_seek()

msql_fetch_row

(PHP 3, PHP 4, PHP 5)

msql_fetch_row -- Get row as enumerated array

Descrizione

array msql_fetch_row ( resource 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.

Elenco dei parametri

result: The result resource that is being evaluated. This result comes from a call to msql_query().

Valori restituiti

Returns an array that corresponds to the fetched row, or FALSE if there are no more rows.

Esempi

Esempio 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); ?>

Log delle modifiche

Versione	Descrizione
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.

Vedere anche:

msql_fetch_array()

msql_fetch_object()

msql_data_seek()

msql_field_flags

(PHP 3 >= 3.0.7, PHP 4, PHP 5)

msql_field_flags -- Get field flags

Descrizione

string msql_field_flags ( resource result, int field_offset )

msql_field_flags() returns the field flags of the specified field.

Elenco dei parametri

result: The result resource that is being evaluated. This result comes from a call to msql_query().
field_offset: The numerical field offset. The field_offset starts at 1.

Valori restituiti

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 3 >= 3.0.7, PHP 4, PHP 5)

msql_field_len -- Get field length

Descrizione

int msql_field_len ( resource result, int field_offset )

msql_field_len() returns the length of the specified field.

Elenco dei parametri

result: The result resource that is being evaluated. This result comes from a call to msql_query().
field_offset: The numerical field offset. The field_offset starts at 1.

Valori restituiti

Returns the length of the specified field or FALSE on error.

msql_field_name

(PHP 3 >= 3.0.7, PHP 4, PHP 5)

msql_field_name -- Get the name of the specified field in a result

Descrizione

string msql_field_name ( resource result, int field_offset )

msql_field_name() gets the name of the specified field index.

Elenco dei parametri

result: The result resource that is being evaluated. This result comes from a call to msql_query().
field_offset: The numerical field offset. The field_offset starts at 1.

Valori restituiti

The name of the field or FALSE on failure.

Vedere anche:

msql_field_len()

msql_field_seek

(PHP 3, PHP 4, PHP 5)

msql_field_seek -- Set field offset

Descrizione

bool msql_field_seek ( resource 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.

Elenco dei parametri

result: The result resource that is being evaluated. This result comes from a call to msql_query().
field_offset: The numerical field offset. The field_offset starts at 1.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

msql_fetch_field()

msql_field_table

(PHP 3 >= 3.0.7, PHP 4, PHP 5)

msql_field_table -- Get table name for field

Descrizione

int msql_field_table ( resource result, int field_offset )

Returns the name of the table that the specified field is in.

Elenco dei parametri

result: The result resource that is being evaluated. This result comes from a call to msql_query().
field_offset: The numerical field offset. The field_offset starts at 1.

Valori restituiti

The name of the table on success, or FALSE on failure.

msql_field_type

(PHP 3 >= 3.0.7, PHP 4, PHP 5)

msql_field_type -- Get field type

Descrizione

string msql_field_type ( resource result, int field_offset )

msql_field_type() gets the type of the specified field index.

Elenco dei parametri

result: The result resource that is being evaluated. This result comes from a call to msql_query().
field_offset: The numerical field offset. The field_offset starts at 1.

Descrizione

bool msql_free_result ( resource 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.

Elenco dei parametri

result: The result resource that is being evaluated. This result comes from a call to msql_query().

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

msql_list_dbs

(PHP 3, PHP 4, PHP 5)

msql_list_dbs -- List mSQL databases on server

Descrizione

resource msql_list_dbs ( [resource link_identifier] )

msql_list_tables() lists the databases available on the specified link_identifier.

Elenco dei parametri

link_identifier: The mSQL connection. If not specified, the last link opened by msql_connect() is assumed. If no such link is found, the function will try to establish a link as if msql_connect() was called, and use it.

Valori restituiti

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.

Vedere anche:

msql_list_tables()

msql_list_fields()

msql_list_fields

(PHP 3, PHP 4, PHP 5)

msql_list_fields -- List result fields

Descrizione

resource msql_list_fields ( string database, string tablename [, resource link_identifier] )

msql_list_fields() returns information about the given table.

Elenco dei parametri

database: The name of the database.
tablename: The name of the table.
link_identifier: The mSQL connection. If not specified, the last link opened by msql_connect() is assumed. If no such link is found, the function will try to establish a link as if msql_connect() was called, and use it.

Valori restituiti

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.

Vedere anche:

msql_list_tables()

msql_list_dbs()

msql_list_tables

(PHP 3, PHP 4, PHP 5)

msql_list_tables -- List tables in an mSQL database

Descrizione

resource msql_list_tables ( string database [, resource link_identifier] )

msql_list_tables() lists the tables on the specified database.

Elenco dei parametri

database: The name of the database.
link_identifier: The mSQL connection. If not specified, the last link opened by msql_connect() is assumed. If no such link is found, the function will try to establish a link as if msql_connect() was called, and use it.

Valori restituiti

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.

Vedere anche:

msql_list_fields()

msql_list_dbs()

msql_num_fields

(PHP 3, PHP 4, PHP 5)

msql_num_fields -- Get number of fields in result

Descrizione

int msql_num_fields ( resource result )

msql_num_fields() returns the number of fields in a result set.

Elenco dei parametri

result: The result resource that is being evaluated. This result comes from a call to msql_query().

Valori restituiti

Returns the number of fields in the result set.

Vedere anche:

msql_fetch_field()

msql_num_rows()

msql_num_rows

(PHP 3, PHP 4, PHP 5)

msql_num_rows -- Get number of rows in result

Descrizione

int msql_num_rows ( resource query_identifier )

msql_num_rows() returns the number of rows in a result set.

Elenco dei parametri

result: The result resource that is being evaluated. This result comes from a call to msql_query().

Valori restituiti

Returns the number of rows in the result set.

Vedere anche:

msql_num_fields()

msql_numfields

(PHP 3, PHP 4, PHP 5)

msql_numfields -- Alias of msql_num_fields()

Descrizione

This function is an alias of msql_num_fields().

msql_numrows

(PHP 3, PHP 4, PHP 5)

msql_numrows -- Alias of msql_num_rows()

Descrizione

This function is an alias of msql_num_rows().

msql_pconnect

(PHP 3, PHP 4, PHP 5)

msql_pconnect -- Open persistent mSQL connection

Descrizione

resource msql_pconnect ( [string hostname] )

msql_pconnect() acts very much like msql_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. 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 (msql_close() will not close links established by this function).

Elenco dei parametri

hostname

The hostname can also include a port number. e.g. hostname,port.

If not specified, the connection is established by the means of a Unix domain socket, being then more efficient then a localhost TCP socket connection.

Nota: While this function will accept a colon (:) as a host/port separator, a comma (,) is the preferred method.

Valori restituiti

Returns a positive mSQL link identifier on success, or FALSE on error.

Vedere anche:

msql_close()

msql_query

(PHP 3, PHP 4, PHP 5)

msql_query -- Send mSQL query

Descrizione

resource msql_query ( string 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.

Elenco dei parametri

query: The SQL query.
link_identifier: The mSQL connection. If not specified, the last link opened by msql_connect() is assumed. If no such link is found, the function will try to establish a link as if msql_connect() was called, and use it.

Valori restituiti

Returns a positive mSQL query identifier on success, or FALSE on error.

Esempi

Esempio 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"]; } ?>

Vedere anche:

msql_db_query()

msql_select_db()

msql_regcase

(PHP 3, PHP 4, PHP 5)

msql_regcase -- Alias of sql_regcase()

Descrizione

This function is an alias of sql_regcase().

msql_result

(PHP 3, PHP 4, PHP 5)

msql_result -- Get result data

Descrizione

string msql_result ( resource result, int row [, mixed field] )

msql_result() returns the contents of one cell from a mSQL result set.

Recommended high-performance alternatives: msql_fetch_row(), msql_fetch_array(), and msql_fetch_object().

Elenco dei parametri

result: The result resource that is being evaluated. This result comes from a call to 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.
Nota: Specifying a numeric field offset is much quicker than specifying a fieldname or tablename.fieldname.

Valori restituiti

Returns the contents of the cell at the row and offset in the specified mSQL result set.

msql_select_db

(PHP 3, PHP 4, PHP 5)

msql_select_db -- Select mSQL database

Descrizione

bool msql_select_db ( string 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.

Elenco dei parametri

database_name: The database name.
link_identifier: The mSQL connection. If not specified, the last link opened by msql_connect() is assumed. If no such link is found, the function will try to establish a link as if msql_connect() was called, and use it.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

msql_pconnect()

mysqli_num_rows() e mysqli_info().

msql_tablename

(PHP 3, PHP 4, PHP 5)

msql_tablename -- Alias of msql_result()

Descrizione

This function is an alias of msql_result().

msql

(PHP 3, PHP 4, PHP 5)

msql -- Alias of msql_db_query()

Descrizione

This function is an alias of msql_db_query().

LXXXIV. Multibyte String Functions

Introduzione

While there are many languages in which every necessary character can be represented by a one-to-one mapping to a 8-bit value, there are also several languages which require so many characters for written communication that cannot be contained within the range a mere byte can code. Multibyte character encoding schemes were developed to express that many (more than 256) characters in the regular bytewise coding system.

When you manipulate (trim, split, splice, etc.) strings encoded in a multibyte encoding, you need to use special functions since two or more consecutive bytes may represent a single character in such encoding schemes. Otherwise, if you apply a non-multibyte-aware string function to the string, it probably fails to detect the beginning or ending of the multibyte character and ends up with a corrupted garbage string that most likely loses its original meaning.

mbstring provides these multibyte specific string functions that help you deal with multibyte encodings in PHP, which is basically supposed to be used with single byte encodings. In addition to that, mbstring handles character encoding conversion between the possible encoding pairs.

mbstring is also designed to handle Unicode-based encodings such as UTF-8 and UCS-2 and many single-byte encodings for convenience (listed below), whereas mbstring was originally developed for use in Japanese web pages.

PHP Character Encoding Requirements

Encodings of the following types are safely used with PHP.

A singlebyte encoding,
- which has ASCII-compatible (ISO646 compatible) mappings for the characters in range of 00h to 7fh.
A multibyte encoding,
- which has ASCII-compatible mappings for the characters in range of 00h to 7fh.
- which don't use ISO2022 escape sequences.
- which don't use a value from 00h to 7fh in any of the compounded bytes that represents a single character.

These are examples of character encodings that are unlikely to work with PHP.

JIS, SJIS, ISO-2022-JP, BIG-5

Although PHP scripts written in any of those encodings might not work, especially in the case where encoded strings appear as identifiers or literals in the script, you can almost avoid using these encodings by setting up the mbstring's transparent encoding filter function for incoming HTTP queries.

Nota: It's highly discouraged to use SJIS, BIG5, CP936, CP949 and GB18030 for the internal encoding unless you are familiar with the parser, the scanner and the character encoding.

Nota: If you have some database connected with PHP, it is recommended that you use the same character encoding for both database and the internal encoding for ease of use and better performance.
If you are using PostgreSQL, the character encoding used in the database and the one used in the PHP may differ as it supports automatic character set conversion between the backend and the frontend.

Installazione

mbstring is a non-default extension. This means it is not enabled by default. You must explicitly enable the module with the configure option. See the Install section for details.

The following configure options are related to the mbstring module.

--enable-mbstring=LANG: Enable mbstring functions. This option is required to use mbstring functions.
As of PHP 4.3.0, mbstring extension provides enhanced support for Simplified Chinese, Traditional Chinese, Korean, and Russian in addition to Japanese. To enable that feature, you will have to supply either one of the following options to the LANG parameter; --enable-mbstring=cn for Simplified Chinese support, --enable-mbstring=tw for Traditional Chinese support, --enable-mbstring=kr for Korean support, --enable-mbstring=ru for Russian support, and --enable-mbstring=ja for Japanese support.
Also --enable-mbstring=all is convenient for you to enable all the supported languages listed above.
Nota: Japanese language support is also enabled by --enable-mbstring without any options for the sake of backwards compatibility.
--enable-mbstr-enc-trans : Enable HTTP input character encoding conversion using mbstring conversion engine. If this feature is enabled, HTTP input character encoding may be converted to mbstring.internal_encoding automatically.
Nota: As of PHP 4.3.0, the option --enable-mbstr-enc-trans was eliminated and replaced with the runtime setting mbstring.encoding_translation. HTTP input character encoding conversion is enabled when this is set to On (the default is Off).
--enable-mbregex: Enable regular expression functions with multibyte character support.

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

Tabella 1. mbstring configuration options

Name	Default	Changeable	Changelog
mbstring.language	"neutral"	PHP_INI_PERDIR	Available since PHP 4.3.0.
mbstring.detect_order	NULL	PHP_INI_ALL	Available since PHP 4.0.6.
mbstring.http_input	"pass"	PHP_INI_ALL	Available since PHP 4.0.6.
mbstring.http_output	"pass"	PHP_INI_ALL	Available since PHP 4.0.6.
mbstring.internal_encoding	NULL	PHP_INI_ALL	Available since PHP 4.0.6.
mbstring.script_encoding	NULL	PHP_INI_ALL	Available since PHP 4.3.0.
mbstring.substitute_character	NULL	PHP_INI_ALL	Available since PHP 4.0.6.
mbstring.func_overload	"0"	PHP_INI_PERDIR	PHP_INI_SYSTEM in PHP <= 4.2.3. Available since PHP 4.2.0.
mbstring.encoding_translation	"0"	PHP_INI_PERDIR	Available since PHP 4.3.0.

For the definition of the PHP_INI_* constants, please refer to ini_set().

Breve descrizione dei parametri di configurazione.

mbstring.language string: The default national language setting (NLS) used in mbstring. Note that this option automagically defines mbstring.internal_encoding and mbstring.internal_encoding should be placed after mbstring.language in php.ini
mbstring.encoding_translation boolean: Enables the transparent character encoding filter for the incoming HTTP queries, which performs detection and conversion of the input encoding to the internal character encoding.
mbstring.internal_encoding string: Defines the default internal character encoding.
mbstring.http_input string: Defines the default HTTP input character encoding.
mbstring.http_output string: Defines the default HTTP output character encoding.
mbstring.detect_order string: Defines default character code detection order. See also mb_detect_order().
mbstring.substitute_character string: Defines character to substitute for invalid character encoding.
mbstring.func_overload string: Overloads a set of single byte functions by the mbstring counterparts. See Function overloading for more information.

According to the HTML 4.01 specification, Web browsers are allowed to encode a form being submitted with a character encoding different from the one used for the page. See mb_http_input() to detect character encoding used by browsers.

Although popular browsers are capable of giving a reasonably accurate guess to the character encoding of a given HTML document, it would be better to set the charset parameter in the Content-Type HTTP header to the appropriate value by header() or default_charset ini setting.

Esempio 1. php.ini setting examples
; Set default language mbstring.language = Neutral; Set default language to Neutral(UTF-8) (default) mbstring.language = English; Set default language to English mbstring.language = Japanese; Set default language to Japanese ;; Set default internal encoding ;; Note: Make sure to use character encoding works with PHP mbstring.internal_encoding = UTF-8 ; Set internal encoding to UTF-8 ;; HTTP input encoding translation is enabled. mbstring.encoding_translation = On ;; Set default HTTP input character encoding ;; Note: Script cannot change http_input setting. mbstring.http_input = pass ; No conversion. mbstring.http_input = auto ; Set HTTP input to auto ; "auto" is expanded to "ASCII,JIS,UTF-8,EUC-JP,SJIS" mbstring.http_input = SJIS ; Set HTTP2 input to SJIS mbstring.http_input = UTF-8,SJIS,EUC-JP ; Specify order ;; Set default HTTP output character encoding mbstring.http_output = pass ; No conversion mbstring.http_output = UTF-8 ; Set HTTP output encoding to UTF-8 ;; Set default character encoding detection order mbstring.detect_order = auto ; Set detect order to auto mbstring.detect_order = ASCII,JIS,UTF-8,SJIS,EUC-JP ; Specify order ;; Set default substitute character mbstring.substitute_character = 12307 ; Specify Unicode value mbstring.substitute_character = none ; Do not print character mbstring.substitute_character = long ; Long Example: U+3000,JIS+7E7E

Esempio 2. php.ini setting for EUC-JP users
;; Disable Output Buffering output_buffering = Off ;; Set HTTP header charset default_charset = EUC-JP ;; Set default language to Japanese mbstring.language = Japanese ;; HTTP input encoding translation is enabled. mbstring.encoding_translation = On ;; Set HTTP input encoding conversion to auto mbstring.http_input = auto ;; Convert HTTP output to EUC-JP mbstring.http_output = EUC-JP ;; Set internal encoding to EUC-JP mbstring.internal_encoding = EUC-JP ;; Do not print invalid characters mbstring.substitute_character = none

Esempio 3. php.ini setting for SJIS users
;; Enable Output Buffering output_buffering = On ;; Set mb_output_handler to enable output conversion output_handler = mb_output_handler ;; Set HTTP header charset default_charset = Shift_JIS ;; Set default language to Japanese mbstring.language = Japanese ;; Set http input encoding conversion to auto mbstring.http_input = auto ;; Convert to SJIS mbstring.http_output = SJIS ;; Set internal encoding to EUC-JP mbstring.internal_encoding = EUC-JP ;; Do not print invalid characters mbstring.substitute_character = none

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

MB_OVERLOAD_MAIL (integer)
MB_OVERLOAD_STRING (integer)
MB_OVERLOAD_REGEX (integer)

HTTP Input and Output

HTTP input/output character encoding conversion may convert binary data also. Users are supposed to control character encoding conversion if binary data is used for HTTP input/output.

Nota: In PHP 4.3.2 or earlier versions, there was a limitation in this functionality that mbstring does not perform character encoding conversion in POST data if the enctype attribute in the form element is set to multipart/form-data. So you have to convert the incoming data by yourself in this case if necessary.
Beginning with PHP 4.3.3, if enctype for HTML form is set to multipart/form-data and mbstring.encoding_translation is set to On in php.ini the POST'ed variables and the names of uploaded files will be converted to the internal character encoding as well. However, the conversion isn't applied to the query keys.

HTTP Input

There is no way to control HTTP input character conversion from PHP script. To disable HTTP input character conversion, it has to be done in php.ini.
Esempio 4. Disable HTTP input conversion in php.ini
;; Disable HTTP Input conversion mbstring.http_input = pass ;; Disable HTTP Input conversion (PHP 4.3.0 or higher) mbstring.encoding_translation = Off

When using PHP as an Apache module, it is possible to override those settings in each Virtual Host directive in httpd.conf or per directory with .htaccess. Refer to the Configuration section and Apache Manual for details.

HTTP Output
There are several ways to enable output character encoding conversion. One is using php.ini, another is using ob_start() with mb_output_handler() as ob_start callback function.
Nota: PHP3-i18n users should note that mbstring's output conversion differs from PHP3-i18n. Character encoding is converted using output buffer.

Esempio 5. php.ini setting example
;; Enable output character encoding conversion for all PHP pages ;; Enable Output Buffering output_buffering = On ;; Set mb_output_handler to enable output conversion output_handler = mb_output_handler

Esempio 6. Script example
<?php // Enable output character encoding conversion only for this page // Set HTTP output character encoding to SJIS mb_http_output('SJIS'); // Start buffering and specify "mb_output_handler" as // callback function ob_start('mb_output_handler'); ?>

Supported Character Encodings

Currently the following character encodings are supported by the mbstring module. Any of those Character encodings can be specified in the encoding parameter of mbstring functions.

The following character encoding is supported in this PHP extension:

UCS-4
UCS-4BE
UCS-4LE
UCS-2
UCS-2BE
UCS-2LE
UTF-32
UTF-32BE
UTF-32LE
UTF-16
UTF-16BE
UTF-16LE
UTF-7
UTF7-IMAP
UTF-8
ASCII
EUC-JP
SJIS
eucJP-win
SJIS-win
ISO-2022-JP
JIS
ISO-8859-1
ISO-8859-2
ISO-8859-3
ISO-8859-4
ISO-8859-5
ISO-8859-6
ISO-8859-7
ISO-8859-8
ISO-8859-9
ISO-8859-10
ISO-8859-13
ISO-8859-14
ISO-8859-15
byte2be
byte2le
byte4be
byte4le
BASE64
HTML-ENTITIES
7bit
8bit
EUC-CN
CP936
HZ
EUC-TW
CP950
BIG-5
EUC-KR
UHC (CP949)
ISO-2022-KR
Windows-1251 (CP1251)
Windows-1252 (CP1252)
CP866 (IBM866)
KOI8-R

php.ini entry, which accepts encoding name, accepts "auto" and "pass" also. mbstring functions, which accepts encoding name, and accepts "auto".

If "pass" is set, no character encoding conversion is performed.

If "auto" is set, it is expanded to the list of encodings defined per the NLS. For instance, if the NLS is set to Japanese, the value is assumed to be "ASCII,JIS,UTF-8,EUC-JP,SJIS".

Function Overloading Feature

You might often find it difficult to get an existing PHP application work in a given multibyte environment. That's mostly because lots of PHP applications out there are written with the standard string functions such as substr(), which are known to not properly handle multibyte-encoded strings.

mbstring supports 'function overloading' feature which enables you to add multibyte awareness to such an application without code modification by overloading multibyte counterparts on the standard string functions. For example, mb_substr() is called instead of substr() if function overloading is enabled. This feature makes it easy to port applications that only support single-byte encodings to a multibyte environment in many cases.

To use the function overloading, set mbstring.func_overload in php.ini to a positive value that represents a combination of bitmasks specifying the categories of functions to be overloaded. It should be set to 1 to overload the mail() function. 2 for string functions, 4 for regular expression functions. For example, if is set for 7, mail, strings and regular expression functions should be overloaded. The list of overloaded functions are shown below.

Tabella 2. Functions to be overloaded

value of mbstring.func_overload	original function	overloaded function
1	mail()	mb_send_mail()
2	strlen()	mb_strlen()
2	strpos()	mb_strpos()
2	strrpos()	mb_strrpos()
2	substr()	mb_substr()
2	strtolower()	mb_strtolower()
2	strtoupper()	mb_strtoupper()
2	substr_count()	mb_substr_count()
4	ereg()	mb_ereg()
4	eregi()	mb_eregi()
4	ereg_replace()	mb_ereg_replace()
4	eregi_replace()	mb_eregi_replace()
4	split()	mb_split()

Nota: It is not recommended to use the function overloading option in the per-directory context, because it's not confirmed yet to be stable enough in a production environment and may lead to undefined behaviour.

Basics of Japanese multi-byte encodings

It is often said quite hard to figure out how Japanese texts are handled in the computer. This is not only because Japanese characters can only be represented by multibyte encodings, but because different encoding standards are adopted for different purposes / platforms. Moreover, not a few character set standards are used there, which are slightly different from one another. Those facts have often led developers to inevitable mess-up.

To create a working web application that would be put in the Japanese environment, it is important to use the proper character encoding and character set for the task in hand.

Storage for a character can be up to six bytes
Most of multibyte characters often appear twice as wide as a single-byte character on display. Those characters are called "zen-kaku" in Japanese which means "full width", and the other (narrower) characters are called "han-kaku" - means half width. However the graphical properties of the characters depend on the glyphs of the type faces used to display them or print them out.
Some character encodings use shift(escape) sequences defined in ISO2022 to switch the code map of the specific code area (00h to 7fh).
ISO-2022-JP should be used in SMTP/NNTP, and headers and entities should be reencoded as per RFC requirements. Although those are not requisites, it's still a good idea because several popular user agents cannot recognize any other encoding methods.
Webpages created for mobile phone services such as i-mode, Vodafone live!, or EZweb are supposed to use Shift_JIS.

References

Multibyte character encoding schemes and the related issues are very complicated. There should be too few space to cover in sufficient details. Please refer to the following URLs and other resources for further readings.

Unicode materials
http://www.unicode.org/
Japanese/Korean/Chinese character information
http://examples.oreilly.com/cjkvinfo/doc/cjk.inf

Summaries of supported encodings

Summaries of supported encodings

Name in the IANA character set registry: ISO-10646-UCS-4

Underlying character set: ISO 10646

Description: The Universal Character Set with 31-bit code space, standardized as UCS-4 by ISO/IEC 10646. It is kept synchronized with the latest version of the Unicode code map.

Additional note: If this name is used in the encoding conversion facility, the converter attempts to identify by the preceding BOM (byte order mark)in which endian the subsequent bytes are represented.

Name in the IANA character set registry: ISO-10646-UCS-4

Underlying character set: UCS-4

Description: See above.

Additional note: In contrast to UCS-4, strings are always assumed to be in big endian form.

Name in the IANA character set registry: ISO-10646-UCS-4

Underlying character set: UCS-4

Description: See above.

Additional note: In contrast to UCS-4, strings are always assumed to be in little endian form.

Name in the IANA character set registry: ISO-10646-UCS-2

Underlying character set: UCS-2

Description: The Universal Character Set with 16-bit code space, standardized as UCS-2 by ISO/IEC 10646. It is kept synchronized with the latest version of the unicode code map.

Name in the IANA character set registry: ISO-10646-UCS-2

Underlying character set: UCS-2

Description: See above.

Additional note: In contrast to UCS-2, strings are always assumed to be in big endian form.

Name in the IANA character set registry: ISO-10646-UCS-2

Underlying character set: UCS-2

Description: See above.

Additional note: In contrast to UCS-2, strings are always assumed to be in little endian form.

Name in the IANA character set registry: UTF-32

Underlying character set: Unicode

Description: Unicode Transformation Format of 32-bit unit width, whose encoding space refers to the Unicode's codeset standard. This encoding scheme wasn't identical to UCS-4 because the code space of Unicode were limited to a 21-bit value.

Name in the IANA character set registry: UTF-32BE

Underlying character set: Unicode

Description: See above

Additional note: In contrast to UTF-32, strings are always assumed to be in big endian form.

Name in the IANA character set registry: UTF-32LE

Underlying character set: Unicode

Description: See above

Additional note: In contrast to UTF-32, strings are always assumed to be in little endian form.

Name in the IANA character set registry: UTF-16

Underlying character set: Unicode

Description: Unicode Transformation Format of 16-bit unit width. It's worth a note that UTF-16 is no longer the same specification as UCS-2 because the surrogate mechanism has been introduced since Unicode 2.0 and UTF-16 now refers to a 21-bit code space.

Name in the IANA character set registry: UTF-16BE

Underlying character set: Unicode

Description: See above.

Additional note: In contrast to UTF-16, strings are always assumed to be in big endian form.

Name in the IANA character set registry: UTF-16BE

Underlying character set: Unicode

Description: See above.

Additional note: In contrast to UTF-16, strings are always assumed to be in big endian form.

Name in the IANA character set registry: UTF-8

Underlying character set: Unicode / UCS

Description: Unicode Transformation Format of 8-bit unit width.

Additional note: none

Name in the IANA character set registry: UTF-7

Underlying character set: Unicode

Description: A mail-safe transformation format of Unicode, specified in RFC2152.

Additional note: none

Name in the IANA character set registry: (none)

Underlying character set: Unicode

Description: A variant of UTF-7 which is specialized for use in the IMAP protocol.

Additional note: none

Name in the IANA character set registry: US-ASCII (preferred MIME name) / iso-ir-6 / ANSI_X3.4-1986 / ISO_646.irv:1991 / ASCII / ISO646-US / us / IBM367 / CP367 / csASCII

Underlying character set: ASCII / ISO 646

Description: American Standard Code for Information Interchange is a commonly-used 7-bit encoding. Also standardized as an international standard, ISO 646.

Additional note: (none)

Name in the IANA character set registry: EUC-JP (preferred MIME name) / Extended_UNIX_Code_Packed_Format_for_Japanese / csEUCPkdFmtJapanese

Underlying character set: Compound of US-ASCII / JIS X0201:1997 (hankaku kana part) / JIS X0208:1990 / JIS X0212:1990

Description: As you see the name is derived from an abbreviation of Extended UNIX Code Packed Format for Japanese, this encoding is mostly used on UNIX or alike platforms. The original encoding scheme, Extended UNIX Code, is designed on the basis of ISO 2022.

Additional note: The character set referred to by EUC-JP is different to IBM932 / CP932, which are used by OS/2® and Microsoft® Windows®. For information interchange with those platforms, use EUCJP-WIN instead.

Name in the IANA character set registry: Shift_JIS (preferred MIME name) / MS_Kanji / csShift_JIS

Underlying character set: Compound of JIS X0201:1997 / JIS X0208:1997

Description: Shift_JIS was developed in early 80's, at the time personal Japanese word processors were brought into the market, in order to maintain compatiblities with the legacy encoding scheme JIS X 0201:1976. According to the IANA definition the codeset of Shift_JIS is slightly different to IBM932 / CP932. However, the names "SJIS" / "Shift_JIS" are often wrongly used to refer to these codesets.

Additional note: For the CP932 codemap, use SJIS-WIN instead.

Name in the IANA character set registry: (none)

Underlying character set: Compound of JIS X0201:1997 / JIS X0208:1997 / IBM extensions / NEC extensions

Description: While this "encoding" uses the same encoding scheme as EUC-JP, the underlying character set is different. That is, some code points map to different characters than EUC-JP.

Additional note: none

Name in the IANA character set registry: Windows-31J / csWindows31J

Underlying character set: Compound of JIS X0201:1997 / JIS X0208:1997 / IBM extensions / NEC extensions

Description: While this "encoding" uses the same encoding scheme as Shift_JIS, the underlying character set is different. That means some code points map to different characters than Shift_JIS.

Additional note: (none)

Name in the IANA character set registry: ISO-2022-JP (preferred MIME name) / csISO2022JP

Underlying character set: US-ASCII / JIS X0201:1976 / JIS X0208:1978 / JIS X0208:1983

Description: RFC1468

Additional note: (none)

Name in the IANA character set registry: JIS

Underlying character set:

Description:

Additional note:

Name in the IANA character set registry: ISO-8859-1

Underlying character set:

Description:

Additional note:

Name in the IANA character set registry: ISO-8859-2

Underlying character set:

Description:

Additional note:

Name in the IANA character set registry: ISO-8859-3

Underlying character set:

Description:

Additional note:

Name in the IANA character set registry: ISO-8859-4

Underlying character set:

Description:

Additional note:

Name in the IANA character set registry: ISO-8859-5

Underlying character set:

Description:

Additional note:

Name in the IANA character set registry: ISO-8859-6

Underlying character set:

Description:

Additional note:

Name in the IANA character set registry: ISO-8859-7

Underlying character set:

Description:

Additional note:

Name in the IANA character set registry: ISO-8859-8

Underlying character set:

Description:

Additional note:

Name in the IANA character set registry: ISO-8859-9

Underlying character set:

Description:

Additional note:

Name in the IANA character set registry: ISO-8859-10

Underlying character set:

Description:

Additional note:

Name in the IANA character set registry: ISO-8859-13

Underlying character set:

Description:

Additional note:

Name in the IANA character set registry: ISO-8859-14

Underlying character set:

Description:

Additional note:

Name in the IANA character set registry: ISO-8859-15

Underlying character set:

Description:

Additional note:

Name in the IANA character set registry: byte2be

Underlying character set:

Description:

Additional note:

Name in the IANA character set registry: byte2le

Underlying character set:

Description:

Additional note:

Name in the IANA character set registry: byte4be

Underlying character set:

Description:

Additional note:

Name in the IANA character set registry: byte4le

Underlying character set:

Description:

Additional note:

Name in the IANA character set registry: BASE64

Underlying character set:

Description:

Additional note:

Name in the IANA character set registry: HTML-ENTITIES

Underlying character set:

Description:

Additional note:

Name in the IANA character set registry: 7bit

Underlying character set:

Description:

Additional note:

Name in the IANA character set registry: 8bit

Underlying character set:

Description:

Additional note:

Name in the IANA character set registry: EUC-CN

Underlying character set:

Description:

Additional note:

Name in the IANA character set registry: CP936

Underlying character set:

Description:

Additional note:

Name in the IANA character set registry: HZ

Underlying character set:

Description:

Additional note:

Name in the IANA character set registry: EUC-TW

Underlying character set:

Description:

Additional note:

Name in the IANA character set registry: CP950

Underlying character set:

Description:

Additional note:

Name in the IANA character set registry: BIG-5

Underlying character set:

Description:

Additional note:

Name in the IANA character set registry: EUC-KR

Underlying character set:

Description:

Additional note:

Name in the IANA character set registry: UHC (CP949)

Underlying character set:

Description:

Additional note:

Name in the IANA character set registry: ISO-2022-KR

Underlying character set:

Description:

Additional note:

Name in the IANA character set registry: Windows-1251 (CP1251)

Underlying character set:

Description:

Additional note:

Name in the IANA character set registry: Windows-1252 (CP1252)

Underlying character set:

Description:

Additional note:

Name in the IANA character set registry: CP866 (IBM866)

Underlying character set:

Description:

Additional note:

Name in the IANA character set registry: KOI8-R

Underlying character set:

Description:

Additional note:

Sommario
mb_convert_case -- Perform case folding on a string
mb_convert_encoding -- Convert character encoding
mb_convert_kana -- Convert "kana" one from another ("zen-kaku", "han-kaku" and more)
mb_convert_variables -- Convert character code in variable(s)
mb_decode_mimeheader -- Decode string in MIME header field
mb_decode_numericentity -- Decode HTML numeric string reference to character
mb_detect_encoding -- Detect character encoding
mb_detect_order -- Set/Get character encoding detection order
mb_encode_mimeheader -- Encode string for MIME header
mb_encode_numericentity -- Encode character to HTML numeric string reference
mb_ereg_match -- Regular expression match for multibyte string
mb_ereg_replace -- Replace regular expression with multibyte support
mb_ereg_search_getpos -- Returns start point for next regular expression match
mb_ereg_search_getregs -- Retrieve the result from the last multibyte regular expression match
mb_ereg_search_init -- Setup string and regular expression for multibyte regular expression match
mb_ereg_search_pos -- Return position and length of matched part of multibyte regular expression for predefined multibyte string
mb_ereg_search_regs -- Returns the matched part of multibyte regular expression
mb_ereg_search_setpos -- Set start point of next regular expression match
mb_ereg_search -- Multibyte regular expression match for predefined multibyte string
mb_ereg -- Regular expression match with multibyte support
mb_eregi_replace -- Replace regular expression with multibyte support ignoring case
mb_eregi -- Regular expression match ignoring case with multibyte support
mb_get_info -- Get internal settings of mbstring
mb_http_input -- Detect HTTP input character encoding
mb_http_output -- Set/Get HTTP output character encoding
mb_internal_encoding -- Set/Get internal character encoding
mb_language -- Set/Get current language
mb_list_encodings -- Returns an array of all supported encodings
mb_output_handler -- Callback function converts character encoding in output buffer
mb_parse_str -- Parse GET/POST/COOKIE data and set global variable
mb_preferred_mime_name -- Get MIME charset string
mb_regex_encoding -- Returns current encoding for multibyte regex as string
mb_regex_set_options -- Set/Get the default options for mbregex functions
mb_send_mail -- Send encoded mail
mb_split -- Split multibyte string using regular expression
mb_strcut -- Get part of string
mb_strimwidth -- Get truncated string with specified width
mb_strlen -- Get string length
mb_strpos -- Find position of first occurrence of string in a string
mb_strrpos -- Find position of last occurrence of a string in a string
mb_strtolower -- Make a string lowercase
mb_strtoupper -- Make a string uppercase
mb_strwidth -- Return width of string
mb_substitute_character -- Set/Get substitution character
mb_substr_count -- Count the number of substring occurrences
mb_substr -- Get part of string

mb_convert_case

(PHP 4 >= 4.3.0, PHP 5)

mb_convert_case -- Perform case folding on a string

Description

string mb_convert_case ( string str, int mode [, string encoding] )

mb_convert_case() returns case folded version of string converted in the way specified by mode.

mode can be one of MB_CASE_UPPER, MB_CASE_LOWER or MB_CASE_TITLE.

encoding specifies the encoding of str; if omitted, the internal character encoding value will be used.

The return value is str with the appropriate case folding applied.

By contrast to the standard case folding functions such as strtolower() and strtoupper(), case folding is performed on the basis of the Unicode character properties. Thus the behaviour of this function is not affected by locale settings and it can convert any characters that have 'alphabetic' property, such as A-umlaut (Ä).

For more information about the Unicode properties, please see http://www.unicode.org/unicode/reports/tr21/.

Esempio 1. mb_convert_case() example
<?php $str = "mary had a Little lamb and she loved it so"; $str = mb_convert_case($str, MB_CASE_UPPER, "UTF-8"); echo $str; // Prints MARY HAD A LITTLE LAMB AND SHE LOVED IT SO $str = mb_convert_case($str, MB_CASE_TITLE, "UTF-8"); echo $str; // Prints Mary Had A Little Lamb And She Loved It So ?>

mb_convert_encoding

(PHP 4 >= 4.0.6, PHP 5)

mb_convert_encoding -- Convert character encoding

Description

string mb_convert_encoding ( string str, string to_encoding [, mixed from_encoding] )

mb_convert_encoding() converts character encoding of string str from from_encoding to to_encoding.

str : String to be converted.

from_encoding is specified by character code name before conversion. it can be array or string - comma separated enumerated list. If it is not specified, the internal encoding will be used.

Esempio 1. mb_convert_encoding() example
<?php /* Convert internal character encoding to SJIS */ $str = mb_convert_encoding($str, "SJIS"); /* Convert EUC-JP to UTF-7 */ $str = mb_convert_encoding($str, "UTF-7", "EUC-JP"); /* Auto detect encoding from JIS, eucjp-win, sjis-win, then convert str to UCS-2LE */ $str = mb_convert_encoding($str, "UCS-2LE", "JIS, eucjp-win, sjis-win"); /* "auto" is expanded to "ASCII,JIS,UTF-8,EUC-JP,SJIS" */ $str = mb_convert_encoding($str, "EUC-JP", "auto"); ?>

mb_convert_kana

(PHP 4 >= 4.0.6, PHP 5)

mb_convert_kana -- Convert "kana" one from another ("zen-kaku", "han-kaku" and more)

Description

string mb_convert_kana ( string str [, string option [, string encoding]] )

mb_convert_kana() performs "han-kaku" - "zen-kaku" conversion for string str. It returns converted string. This function is only useful for Japanese.

option is conversion option. Default value is "KV".

encoding is character encoding. If it is omitted, internal character encoding is used.

Specify with combination of following options. Default value is KV.

Tabella 1. Applicable Conversion Options

Option	Meaning
`r`	Convert "zen-kaku" alphabets to "han-kaku"
`R`	Convert "han-kaku" alphabets to "zen-kaku"
`n`	Convert "zen-kaku" numbers to "han-kaku"
`N`	Convert "han-kaku" numbers to "zen-kaku"
`a`	Convert "zen-kaku" alphabets and numbers to "han-kaku"
`A`	Convert "han-kaku" alphabets and numbers to "zen-kaku" (Characters included in "a", "A" options are U+0021 - U+007E excluding U+0022, U+0027, U+005C, U+007E)
`s`	Convert "zen-kaku" space to "han-kaku" (U+3000 -> U+0020)
`S`	Convert "han-kaku" space to "zen-kaku" (U+0020 -> U+3000)
`k`	Convert "zen-kaku kata-kana" to "han-kaku kata-kana"
`K`	Convert "han-kaku kata-kana" to "zen-kaku kata-kana"
`h`	Convert "zen-kaku hira-gana" to "han-kaku kata-kana"
`H`	Convert "han-kaku kata-kana" to "zen-kaku hira-gana"
`c`	Convert "zen-kaku kata-kana" to "zen-kaku hira-gana"
`C`	Convert "zen-kaku hira-gana" to "zen-kaku kata-kana"
`V`	Collapse voiced sound notation and convert them into a character. Use with "K","H"

Esempio 1. mb_convert_kana() example
<?php /* Convert all "kana" to "zen-kaku" "kata-kana" */ $str = mb_convert_kana($str, "KVC"); /* Convert "han-kaku" "kata-kana" to "zen-kaku" "kata-kana" and "zen-kaku" alpha-numeric to "han-kaku" */ $str = mb_convert_kana($str, "KVa"); ?>

mb_convert_variables

(PHP 4 >= 4.0.6, PHP 5)

mb_convert_variables -- Convert character code in variable(s)

Description

string mb_convert_variables ( string to_encoding, mixed from_encoding, mixed &vars [, mixed &...] )

mb_convert_variables() convert character encoding of variables vars in encoding from_encoding to encoding to_encoding. It returns character encoding before conversion for success, FALSE for failure.

mb_convert_variables() join strings in Array or Object to detect encoding, since encoding detection tends to fail for short strings. Therefore, it is impossible to mix encoding in single array or object.

It from_encoding is specified by array or comma separated string, it tries to detect encoding from from-coding. When encoding is omitted, detect_order is used.

vars (3rd and larger) is reference to variable to be converted. String, Array and Object are accepted. mb_convert_variables() assumes all parameters have the same encoding.

Esempio 1. mb_convert_variables() example
<?php /* Convert variables $post1, $post2 to internal encoding */ $interenc = mb_internal_encoding(); $inputenc = mb_convert_variables($interenc, "ASCII,UTF-8,SJIS-win", $post1, $post2); ?>

mb_decode_mimeheader

(PHP 4 >= 4.0.6, PHP 5)

mixed mb_detect_order ( [mixed encoding_list] )

mb_detect_order() sets automatic character encoding detection order to encoding_list. It returns TRUE for success, FALSE for failure.

encoding_list is array or comma separated list of character encoding. ("auto" is expanded to "ASCII, JIS, UTF-8, EUC-JP, SJIS")

If encoding_list is omitted, it returns current character encoding detection order as array.

This setting affects mb_detect_encoding() and mb_send_mail().

Nota: mbstring currently implements following encoding detection filters. If there is an invalid byte sequence for following encoding, encoding detection will fail.
Nota: UTF-8, UTF-7, ASCII, EUC-JP,SJIS, eucJP-win, SJIS-win, JIS, ISO-2022-JP
For ISO-8859-*, mbstring always detects as ISO-8859-*.
For UTF-16, UTF-32, UCS2 and UCS4, encoding detection will fail always.
Esempio 1. Useless detect order example
; Always detect as ISO-8859-1
detect_order = ISO-8859-1, UTF-8

; Always detect as UTF-8, since ASCII/UTF-7 values are 
; valid for UTF-8
detect_order = UTF-8, ASCII, UTF-7

Esempio 2. mb_detect_order() examples
<?php /* Set detection order by enumerated list */ mb_detect_order("eucjp-win,sjis-win,UTF-8"); /* Set detection order by array */ $ary[] = "ASCII"; $ary[] = "JIS"; $ary[] = "EUC-JP"; mb_detect_order($ary); /* Display current detection order */ echo implode(", ", mb_detect_order()); ?>

mb_encode_mimeheader

(PHP 4 >= 4.0.6, PHP 5)

mb_encode_mimeheader -- Encode string for MIME header

Description

string mb_encode_mimeheader ( string str [, string charset [, string transfer_encoding [, string linefeed]]] )

mb_encode_mimeheader() encodes a given string str by the MIME header encoding scheme. Returns a converted version of the string represented in ASCII.

charset specifies the name of the character set in which str is represented in. The default value is determined by the current NLS setting (mbstring.language).

transfer_encoding specifies the scheme of MIME encoding. It should be either "B" (Base64) or "Q" (Quoted-Printable). Falls back to "B" if not given.

linefeed specifies the EOL (end-of-line) marker with which mb_encode_mime_header() performs line-folding (a RFC term, the act of breaking a line longer than a certain length into multiple lines. The length is currently hard-coded to 74 characters). Falls back to "\r\n" (CRLF) if not given.

Esempio 1. mb_encode_mimeheader() example
<?php $name = ""; // kanji $mbox = "kru"; $doma = "gtinn.mon"; $addr = mb_encode_mimeheader($name, "UTF-7", "Q") . " <" . $mbox . "@" . $doma . ">"; echo $addr; ?>

Nota: This function isn't designed to break lines at higher-level contextual break points (word boundaries, etc.). This behaviour may clutter up the original string with unexpected spaces.

mb_encode_numericentity

(PHP 4 >= 4.0.6, PHP 5)

mb_encode_numericentity -- Encode character to HTML numeric string reference

Description

string mb_encode_numericentity ( string str, array convmap [, string encoding] )

mb_encode_numericentity() converts specified character codes in string str from HTML numeric character reference to character code. It returns converted string.

convmap is array specifies code area to convert.

encoding is character encoding.

Esempio 2. mb_encode_numericentity() example
<?php /* Convert Left side of ISO-8859-1 to HTML numeric character reference */ $convmap = array(0x80, 0xff, 0, 0xff); $str = mb_encode_numericentity($str, $convmap, "ISO-8859-1"); /* Convert user defined SJIS-win code in block 95-104 to numeric string reference */ $convmap = array( 0xe000, 0xe03e, 0x1040, 0xffff, 0xe03f, 0xe0bb, 0x1041, 0xffff, 0xe0bc, 0xe0fa, 0x1084, 0xffff, 0xe0fb, 0xe177, 0x1085, 0xffff, 0xe178, 0xe1b6, 0x10c8, 0xffff, 0xe1b7, 0xe233, 0x10c9, 0xffff, 0xe234, 0xe272, 0x110c, 0xffff, 0xe273, 0xe2ef, 0x110d, 0xffff, 0xe2f0, 0xe32e, 0x1150, 0xffff, 0xe32f, 0xe3ab, 0x1151, 0xffff ); $str = mb_encode_numericentity($str, $convmap, "sjis-win"); ?>

mb_ereg_match

(PHP 4 >= 4.2.0)

mb_ereg_match -- Regular expression match for multibyte string

Description

bool mb_ereg_match ( string pattern, string string [, string option] )

mb_ereg_match() returns TRUE if string matches regular expression pattern, FALSE if not.

The internal encoding or the character encoding specified in mb_regex_encoding() will be used as character encoding.

mb_ereg_replace

(PHP 4 >= 4.2.0)

mb_ereg_replace -- Replace regular expression with multibyte support

Description

string mb_ereg_replace ( string pattern, string replacement, string string [, string option] )

array mb_ereg_search_pos ( [string pattern [, string option]] )

string mb_eregi_replace ( string pattern, string replace, string string [, string option] )

The internal encoding or the character encoding specified in mb_regex_encoding() will be used as character encoding.

mb_eregi

(PHP 4 >= 4.2.0)

mb_eregi -- Regular expression match ignoring case with multibyte support

mixed mb_http_output ( [string encoding] )

If encoding is set, mb_http_output() sets HTTP output character encoding to encoding. Output after this function is converted to encoding. mb_http_output() returns TRUE for success and FALSE for failure.

If encoding is omitted, mb_http_output() returns current HTTP output character encoding.

mb_internal_encoding

(PHP 4 >= 4.0.6, PHP 5)

mb_internal_encoding -- Set/Get internal character encoding

Description

mixed mb_internal_encoding ( [string encoding] )

mb_internal_encoding() sets internal character encoding to encoding If parameter is omitted, it returns current internal encoding.

encoding is used for HTTP input character encoding conversion, HTTP output character encoding conversion and default character encoding for string functions defined by mbstring module.

encoding: Character encoding name

Return Value: If encoding is set,mb_internal_encoding() returns TRUE for success, otherwise returns FALSE. If encoding is omitted, it returns current character encoding name.

Esempio 1. mb_internal_encoding() example
<?php /* Set internal character encoding to UTF-8 */ mb_internal_encoding("UTF-8"); /* Display current internal character encoding */ echo mb_internal_encoding(); ?>

mb_language

(PHP 4 >= 4.0.6, PHP 5)

mb_language -- Set/Get current language

Description

mixed mb_language ( [string language] )

mb_language() sets language. If language is omitted, it returns current language as string.

language setting is used for encoding e-mail messages. Valid languages are "Japanese", "ja","English","en" and "uni" (UTF-8). mb_send_mail() uses this setting to encode e-mail.

Language and its setting is ISO-2022-JP/Base64 for Japanese, UTF-8/Base64 for uni, ISO-8859-1/quoted printable for English.

Return Value: If language is set and language is valid, it returns TRUE. Otherwise, it returns FALSE. When language is omitted, it returns language name as string. If no language is set previously, it returns FALSE.

mb_list_encodings

(PHP 5)

mb_list_encodings -- Returns an array of all supported encodings

Description

array mb_list_encodings ( void )

mb_list_encodings() returns an array with all supported encodings.

Esempio 1. mb_list_encodings() example
<?php print_r(mb_list_encodings()); ?>
Il precedente esempio visualizzerà:
Array ( [0] => pass [1] => auto [2] => wchar [3] => byte2be [4] => byte2le [5] => byte4be [6] => byte4le [7] => BASE64 [8] => UUENCODE [9] => HTML-ENTITIES [10] => Quoted-Printable [11] => 7bit [12] => 8bit [13] => UCS-4 [14] => UCS-4BE [15] => UCS-4LE [16] => UCS-2 [17] => UCS-2BE [18] => UCS-2LE [19] => UTF-32 [20] => UTF-32BE [21] => UTF-32LE [22] => UTF-16 [23] => UTF-16BE [24] => UTF-16LE [25] => UTF-8 [26] => UTF-7 [27] => UTF7-IMAP [28] => ASCII [29] => EUC-JP [30] => SJIS [31] => eucJP-win [32] => SJIS-win [33] => JIS [34] => ISO-2022-JP [35] => Windows-1252 [36] => ISO-8859-1 [37] => ISO-8859-2 [38] => ISO-8859-3 [39] => ISO-8859-4 [40] => ISO-8859-5 [41] => ISO-8859-6 [42] => ISO-8859-7 [43] => ISO-8859-8 [44] => ISO-8859-9 [45] => ISO-8859-10 [46] => ISO-8859-13 [47] => ISO-8859-14 [48] => ISO-8859-15 [49] => EUC-CN [50] => CP936 [51] => HZ [52] => EUC-TW [53] => BIG-5 [54] => EUC-KR [55] => UHC [56] => ISO-2022-KR [57] => Windows-1251 [58] => CP866 [59] => KOI8-R )

mb_output_handler

(PHP 4 >= 4.0.6, PHP 5)

mb_output_handler -- Callback function converts character encoding in output buffer

Description

string mb_output_handler ( string contents, int status )

mb_output_handler() is ob_start() callback function. mb_output_handler() converts characters in output buffer from internal character encoding to HTTP output character encoding.

4.1.0 or later version, this handler adds charset HTTP header when following conditions are met:

Does not set Content-Type by header()
Default MIME type begins with text/
http_output setting is other than pass

contents : Output buffer contents

status : Output buffer status

Return Value: String converted

Esempio 1. mb_output_handler() example
<?php mb_http_output("UTF-8"); ob_start("mb_output_handler"); ?>

Nota: If you want to output some binary data such as image from PHP script with PHP 4.3.0 or later, Content-Type: header must be send using header() before any binary data was send to client (e.g. header("Content-Type: image/png")). If Content-Type: header was send, output character encoding conversion will not be performed.
Note that if 'Content-Type: text/*' was send using header(), the sending data is regarded as text, encoding conversion will be performed using character encoding settings.
If you want to output some binary data such as image from PHP script with PHP 4.2.x or earlier, you must set output encoding to "pass" using mb_http_output().

mb_parse_str

(PHP 4 >= 4.0.6, PHP 5)

mb_parse_str -- Parse GET/POST/COOKIE data and set global variable

Description

bool mb_parse_str ( string encoded_string [, array &result] )

mb_parse_str() parses GET/POST/COOKIE data and sets global variables. Since PHP does not provide raw POST/COOKIE data, it can only used for GET data for now. It preses URL encoded data, detects encoding, converts coding to internal encoding and set values to result array or global variables.

bool mb_send_mail ( string to, string subject, string message [, string additional_headers [, string additional_parameter]] )

mb_send_mail() sends email. Headers and message are converted and encoded according to mb_language() setting. mb_send_mail() is wrapper function of mail(). See mail() for details.

to is mail addresses send to. Multiple recipients can be specified by putting a comma between each address in to. This parameter is not automatically encoded.

subject is subject of mail.

message is mail message.

additional_headers is inserted at the end of the header. This is typically used to add extra headers. Multiple extra headers are separated with a newline ("\n").

Nota: Content-Type and Content-Transfer-Encoding headers can be redefined as of PHP 5.0.0. In PHP 4, values defined by mb_language() are always used.

additional_parameter is a MTA command line parameter. It is useful when setting the correct Return-Path header when using sendmail.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

mb_split

(PHP 4 >= 4.2.0)

mb_split -- Split multibyte string using regular expression

Description

array mb_split ( string pattern, string string [, int limit] )

mb_split() split multibyte string using regular expression pattern and returns the result as an array.

If optional parameter limit is specified, it will be split in limit elements as maximum.

The internal encoding or the character encoding specified in mb_regex_encoding() will be used as character encoding.

mb_strcut

(PHP 4 >= 4.0.6, PHP 5)

mb_strcut -- Get part of string

Description

string mb_strcut ( string str, int start [, int length [, string encoding]] )

mb_strcut() returns the portion of str specified by the start and length parameters.

mb_strcut() performs equivalent operation as mb_substr() with different method. If start position is multi-byte character's second byte or larger, it starts from first byte of multi-byte character.

It subtracts string from str that is shorter than length AND character that is not part of multi-byte string or not being middle of shift sequence.

encoding is character encoding. If it is not set, internal character encoding is used.

mb_strimwidth

(PHP 4 >= 4.0.6, PHP 5)

mb_strimwidth -- Get truncated string with specified width

Description

string mb_strimwidth ( string str, int start, int width [, string trimmarker [, string encoding]] )

mb_strimwidth() truncates string str to specified width. It returns truncated string.

If trimmarker is set, trimmarker is appended to return value.

start is start position offset. Number of characters from the beginning of string. (First character is 0)

trimmarker is string that is added to the end of string when string is truncated.

encoding is character encoding. If it is omitted, internal encoding is used.

Esempio 1. mb_strimwidth() example
<?php $str = mb_strimwidth($str, 0, 40, "..>"); ?>

mb_strlen

(PHP 4 >= 4.0.6, PHP 5)

mb_strlen -- Get string length

Description

int mb_strlen ( string str [, string encoding] )

mb_strlen() returns number of characters in string str having character encoding encoding. A multi-byte character is counted as 1.

encoding is character encoding for str. If encoding is omitted, internal character encoding is used.

mb_strpos

(PHP 4 >= 4.0.6, PHP 5)

mb_strpos -- Find position of first occurrence of string in a string

Description

int mb_strpos ( string haystack, string needle [, int offset [, string encoding]] )

mb_strpos() returns the numeric position of the first occurrence of needle in the haystack string. If needle is not found, it returns FALSE.

mb_strpos() performs multi-byte safe strpos() operation based on number of characters. needle position is counted from the beginning of the haystack. First character's position is 0. Second character position is 1, and so on.

If encoding is omitted, internal character encoding is used. mb_strrpos() accepts string for needle where strrpos() accepts only character.

offset is search offset. If it is not specified, 0 is used.

encoding is character encoding name. If it is omitted, internal character encoding is used.

mb_strrpos

(PHP 4 >= 4.0.6, PHP 5)

mb_strrpos -- Find position of last occurrence of a string in a string

int mb_strwidth ( string str [, string encoding] )

mb_strwidth() returns width of string str.

Multi-byte character usually twice of width compare to single byte character.

Tabella 1. Characters width

Chars	Width
U+0000 - U+0019	0
U+0020 - U+1FFF	1
U+2000 - U+FF60	2
U+FF61 - U+FF9F	1
U+FFA0 -	2

encoding is character encoding. If it is omitted, internal encoding is used.

mb_substitute_character

(PHP 4 >= 4.0.6, PHP 5)

mb_substitute_character -- Set/Get substitution character

Description

mixed mb_substitute_character ( [mixed substrchar] )

mb_substitute_character() specifies substitution character when input character encoding is invalid or character code is not exist in output character encoding. Invalid characters may be substituted NULL(no output), string or integer value (Unicode character code value).

This setting affects mb_convert_encoding(), mb_convert_variables(), mb_output_handler(), and mb_send_mail().

substchar : Specify Unicode value as integer or specify as string as follows

"none" : no output
"long" : Output character code value (Example: U+3000,JIS+7E7E)

Return Value: If substchar is set, it returns TRUE for success, otherwise returns FALSE. If substchar is not set, it returns Unicode value or "none"/"long".

Esempio 1. mb_substitute_character() example
<?php /* Set with Unicode U+3013 (GETA MARK) */ mb_substitute_character(0x3013); /* Set hex format */ mb_substitute_character("long"); /* Display current setting */ echo mb_substitute_character(); ?>

mb_substr_count

(PHP 4 >= 4.3.0, PHP 5)

mb_substr_count -- Count the number of substring occurrences

Description

int mb_substr_count ( string haystack, string needle [, string encoding] )

mb_substr_count() returns the number of times the needle substring occurs in the haystack string.

encoding specifies the encoding for needle and haystack. If omitted, internal character encoding is used.

Esempio 1. mb_substr_count() example
<?php echo mb_substr_count("This is a test", "is"); // prints out 2 ?>

mb_substr

(PHP 4 >= 4.0.6, PHP 5)

mb_substr -- Get part of string

Description

string mb_substr ( string str, int start [, int length [, string encoding]] )

mb_substr() returns the portion of str specified by the start and length parameters.

mb_substr() performs multi-byte safe substr() operation based on number of characters. Position is counted from the beginning of str. First character's position is 0. Second character position is 1, and so on.

If encoding is omitted, internal encoding is assumed.

encoding is character encoding. If it is omitted, internal character encoding is used.

LXXXV. muscat Functions

Introduzione

Avvertimento

Installazione

These functions are only available if PHP was configured with --with-muscat[=DIR].

Sommario
muscat_close -- Shuts down the muscat session and releases any memory back to PHP
muscat_get -- Gets a line back from the core muscat API
muscat_give -- Sends string to the core muscat API
muscat_setup_net -- Creates a new muscat session and returns the handle
muscat_setup -- Creates a new muscat session and returns the handle

(4.0.5 - 4.2.3 only, PECL)

muscat_setup_net -- Creates a new muscat session and returns the handle

Description

resource muscat_setup_net ( string muscat_host )

Avvertimento

muscat_setup_net() creates a new muscat session and returns the handle.

muscat_host is the hostname to connect to. port is the port number to connect to.

muscat_setup

(4.0.5 - 4.2.3 only, PECL)

muscat_setup -- Creates a new muscat session and returns the handle

Description

resource muscat_setup ( int size [, string muscat_dir] )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

size is the amount of memory in bytes to allocate for muscat. muscat_dir is the muscat installation dir e.g. "/usr/local/empower", it defaults to the compile time muscat directory.

LXXXVI. MySQL Functions

Introduzione

Queste funzioni consentono l'accesso ai server di database MySQL. Maggiori informazioni riguardo MySQL possono essere trovate su http://www.mysql.com/.

La documentazione su MySQL può essere trovata su http://dev.mysql.com/doc/.

Requisiti

Al fine di rendere queste funzioni disponibili, si deve compilare PHP con il supporto MySQL.

Installazione

Usando l'opzione di configurazione --with-mysql[=DIR] si abilita PHP l'accesso ai database MySQL.

In PHP 4, il parametro --with-mysql è abilitato per default. Per disabilitarlo si può utilizzare --without-mysql . Inoltre in PHP 4, se si abilita MySql senza indicare il percorso directory di installazione di MySql, il PHP utilizzerà le librerie incluse nella distribuzione. In Windows non vi sono DLL, è semplicemente compilato nel PHP. Gli utenti che eseguano altre applicazioni basate su MySql (come, ad esempio, auth-mysql), non dovrebbero utilizzare le librerie allegate al PHP, ma, piuttosto, indicare il percorso alla directory di instalalzione di MySQL, come, ad esempio; --with-mysql=/percorso/a/mysql. Questo forzerà PHP ad usare le librerie client installate da MySQL evitando ogni conflitto.

In PHP 5, MySQL non sarà più abilitato per default, e nè la libreria MySQL sarà allegata al PHP. Per maggiori dettagli sul perchè leggere: FAQ.

Questo modulo di interfaccia a MySQL non supporta completamente le tutte le funzioni presenti nelle versioni di MySQL successive alla 4.1.0. Per avere il pieno supporto a queste vedere MySQLi.

Se si desidera installare sia il modulo mysql sia il modulo mysqli utilizzare la stessa libreria client per evitare conflitti.

Avvertimento

Problemi di blocco e di avvio di PHP possono essere riscontrati quando si carica questa estensione insieme ad estensioni recode. Vedere anche l'estensione recode per maggiori informazioni.

Nota: Se occorre utilizzare set di caratteri differenti rispetto al latin (il default), si deve installare la libreria esterna (non allegata al PHP) libmysql compilata con il supporto dei set di caratteri.

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

Tabella 1. Opzioni di configurazione di MySQL

Nome	Predefinito	Modificabile in
mysql.allow_persistent	"On"	PHP_INI_SYSTEM
mysql.max_persistent	"-1"	PHP_INI_SYSTEM
mysql.max_links	"-1"	PHP_INI_SYSTEM
mysql.default_port	NULL	PHP_INI_ALL
mysql.default_socket	NULL	PHP_INI_ALL
mysql.default_host	NULL	PHP_INI_ALL
mysql.default_user	NULL	PHP_INI_ALL
mysql.default_password	NULL	PHP_INI_ALL
mysql.connect_timeout	"0"	PHP_INI_SYSTEM

Per ulteriori dettagli e definizione delle costanti PHP_INI_* vedere ini_set().

Breve descrizione dei parametri di configurazione.

mysql.allow_persistent boolean: Determina se consentire le connessioni persistenti a MySQL.
mysql.max_persistent integer: Il numero massimo di connessioni persistenti MySQL per processo.
mysql.max_links integer: Il numero massimo di connessioni MySQL per processo, incluse le connessioni persistenti.
mysql.default_port string: Il numero di porta TCP predefinito da usare per connettersi ad un server di database se nessuna altra porta viene specificata. Se nessun valore predefinito e specificato, la porta sarà ottenuta dalla variabile d'ambiente MYSQL_TCP_PORT, dalla voce mysql-tcp in /etc/services o dalla costante MYSQL_PORT in fase di compilazione, in questo ordine. Win32 userà solo la costante MYSQL_PORT.
mysql.default_socket string: Il nome del socket predefinito da usare per connettersi ad un server di database locale se nessun altro nome di socket viene specificato.
mysql.default_host string: L'host di default del server da usare per connettersi al server di database se nessun altro host viene specificato. Non si applica in safe mode.
mysql.default_user string: Il nome utente predefinito da usare per connettersi al server di database se nessun altro nome viene specificato. Non si applica in safe mode.
mysql.default_password string: La password predefinita da usare per connettrsi al server di database se nessuna altra password viene specificata. Non si appplica in safe mode.
mysql.connect_timeout integer: Timeout di connessione in secondi. Per Linux questo timeout è usato anche per attendere la prima risposta dal server.

Tipi di risorse

Ci sono due tipi di risorsa usati nel modulo MySQL. Il primo è l'identificativo di connessione per una connessione ad un database, del secondo tipo sono le risorse che contengono i risultati di una query.

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

Fin dal PHP 4.3.0 è possibile specificare flag addizionali per il client per le funzioni mysql_connect() e mysql_pconnect(). Sono definite le seguenti costanti:

Tabella 2. Costanti client MySQL

Costante	Descrizione
MYSQL_CLIENT_COMPRESS	Usa la compressione del protocollo
MYSQL_CLIENT_IGNORE_SPACE	Consente lo spazio dopo i nomi delle funzioni
MYSQL_CLIENT_INTERACTIVE	Lascia trascorrere interactive_timeout secondi (anziché wait_timeout) di inattività prima di chiudere la connessione

La funzione mysql_fetch_array() usa una costante per i diversi tipi di array risultato. Sono definite le seguenti costanti:

Tabella 3. Costanti caricamento MySQL

Costante	Descrizione
MYSQL_ASSOC	Le colonne sono restituite in un array avente il nome del campo come indice dell'array
MYSQL_BOTH	Le colonne sono restituite in un array avente sia un indice numerico sia un indice costituito dal nome del campo
MYSQL_NUM	Le colonne sono restituite in un array avente un indice numerico per i campi. Questo indice inizia da 0, il primo campo nel risultato

Esempi

Questo esempio mostra come connettersi, eseguire una query, stampare le righe risultanti e disconnettersi dal database MySQL.
Esempio 1. Esempio dell'estensione MySQL
<?php /* Connessione e selezione del database */ $connessione = mysql_connect("host_mysql", "utente_mysql", "password_mysql") or die("Connessione non riuscita: " . mysql_error()); print "Connesso con successo"; mysql_select_db("mio_database") or die("Selezione del database non riuscita"); /* Esecuzione di una query SQL */ $query = "SELECT * FROM mia_tabella"; $risultato = mysql_query($query) or die("Query fallita: " . mysql_error() ); /* Stampa dei risultati in HTML */ echo "<table>\n"; while ($linea = mysql_fetch_array($risultato, MYSQL_ASSOC)) { echo "\t<tr>\n"; foreach ($linea as $valore_colonna) { echo "\t\t<td>$valore_colonna</td>\n"; } echo "\t</tr>\n"; } print "</table>\n"; /* Liberazione delle risorse del risultato */ mysql_free_result($risultato); /* Chiusura della connessione */ mysql_close($connessione); ?>

Sommario
mysql_affected_rows -- Ottiene il numero di righe coinvolte nelle precedenti operazioni MySQL
mysql_change_user -- Cambia l'utente della connessione attiva
mysql_client_encoding -- Restituisce il nome del set di caratteri
mysql_close -- Chiude una connessione MySQL
mysql_connect -- Apre una connessione ad un server MySQL
mysql_create_db -- Crea un database MySQL
mysql_data_seek -- Muove il puntatore interno del risultato
mysql_db_name -- Ottiene dei dati dal risultato
mysql_db_query -- Invia una query MySQL
mysql_drop_db -- Elimina (cancella) un database MySQL
mysql_errno -- Restituisce il valore numerico del messaggio di errore della precedente operazione MySQL
mysql_error -- Restituisce il testo del messagio di errore della precedente operazione MySQL
mysql_escape_string -- Aggiunge le sequenze di escape in una stringa per l'uso in mysql_query.
mysql_fetch_array -- Carica una riga del risultato come un array associativo, un array numerico o entrambi.
mysql_fetch_assoc -- Carica una riga del risultato come array associativo
mysql_fetch_field -- Ottiene informazioni sulla colonna da un risultato e le restituisce come oggetto
mysql_fetch_lengths -- Ottiene la lunghezza di ogni output nel risultato
mysql_fetch_object -- Carica una riga del risultato come un ogetto
mysql_fetch_row -- Ottiene una riga del risultato come un array enumerato
mysql_field_flags -- Ottine i flag associati al campo specificato di un risultato
mysql_field_len -- Restituisce la lunghezza del campo specificato
mysql_field_name -- Ottiene il nome del campo specificato in un risultato
mysql_field_seek -- Imposta il puntatore al risultato ad un determinato indice di campo
mysql_field_table -- Ottiene il nome della tabella in cui si trova il campo specificato
mysql_field_type -- Ottiene il tipo del campo specificato in un risultato
mysql_free_result -- Libera la memoria occupata dal risultato
mysql_get_client_info -- Ottine informazioni sul client MySQL
mysql_get_host_info -- Ottiene le informazioni sull'host MySQL
mysql_get_proto_info -- Ottiene le informazion sul protocollo MySQL
mysql_get_server_info -- Ottiene le informazioni sul server MySQL
mysql_info -- Ottiene le informazioni relative alla query più recente.
mysql_insert_id -- Ottiene l'identificativo generato dalla precedente operazione INSERT
mysql_list_dbs -- Elenca i database disponibili in un server MySQL
mysql_list_fields -- Elenca i campi di un risultato MySQL
mysql_list_processes -- Elenca i processi MySQL
mysql_list_tables -- Elenca le tabelle in un database MySQL
mysql_num_fields -- Ottiene il numero di campi nel risultato
mysql_num_rows -- Ottiene il numero di righe in un risultato
mysql_pconnect -- Apre una connessione persiostente ad un server MySQL
mysql_ping -- Esegue un ping su una connessione al server o riconnette se non non esiste la connessione
mysql_query -- Invia una query MySQL
mysql_real_escape_string -- Aggiunge le sequenze di escape ai caratteri speciali in una stringa per l'uso in una istruzione SQL, tenendo conto dell'attuale set di caratteri della connessione.
mysql_result -- Ottiene i dati dal risultato
mysql_select_db -- Seleziona un database MySQL
mysql_stat -- Ottiene l'attuale stato del sistema
mysql_tablename -- Ottiene il nome della tabella
mysql_thread_id -- Restituisce l'attuale thread ID
mysql_unbuffered_query -- Invia una query SQL a MySQL senza caricare e bufferare le righe risultanti

mysql_affected_rows

(PHP 3, PHP 4, PHP 5)

mysql_affected_rows -- Ottiene il numero di righe coinvolte nelle precedenti operazioni MySQL

Descrizione

int mysql_affected_rows ( [resource identificativo_connessione] )

mysql_affected_rows() restituisce il numero di righe coinvolte nell'ultima query INSERT, UPDATE o DELETE associata a identificativo_connessione. Se l'identificativo di connessione non è specificato, viene considerata l'ultima connessione aperta con mysql_connect().

Nota: Se sono usate le transazioni, è necessario richiamare mysql_affected_rows() dopo le query INSERT, UPDATE, o DELETE e non dopo il commit.

Se l'ultima query era una query DELETE senza clausola WHERE, tuti i record saranno cancellati dalla tabella ma questa funzione restituirà zero.

Nota: Usando UPDATE, MySQL non aggiornerà le colonne nelle quali il nuovo valore è uguale al vecchio valore. Questo crea la possibilità che mysql_affected_rows() può non uguagliare realmente il numero di righe corrispondenti ma solo il numero di righe effettivamente coinvolte dalla query.

mysql_affected_rows() non funziona con l'istruzione SELECT ma solo con le istruzioni che modificano i record. Per ricavare il numero di righe restituite da SELECT, usare mysql_num_rows().

Se l'ultima query fallisce, questa funzione restituisce -1.
Esempio 1. Query di eliminazione
<?php /* connessione al database */ mysql_pconnect("localhost", "utente_mysql", "password_mysql") or die("Connessione non riuscita: " . mysql_error()); /* questo dovrebbe restituire il numero corretto di record eliminati */ mysql_query("DELETE FROM mia_tabella WHERE id < 10"); printf ("Records eliminati: %d\n", mysql_affected_rows()); /* senza la clausola WHERE nell'istruzione DELETE, dovrebbe restituire 0 */ mysql_query("DELETE FROM mia_tabella"); printf ("Record eliminati: %d\n", mysql_affected_rows()); ?>
L'esempio riportato sopra dovrebbe produrre il seguente output:
Records eliminati: 10 Records eliminati: 0

Esempio 2. Query di aggiornamento
<?php /* connessione al to database */ mysql_pconnect("localhost", "utente_mysql", "password_mysql") or die("Connessione non riuscita: " . mysql_error()); /* aggiornamento dei record */ mysql_query("UPDATE mia_tabella SET used=1 WHERE id < 10"); printf ("Record aggiornati: %d\n", mysql_affected_rows()); mysql_query("COMMIT"); ?>
L'esempio riportato sopra dovrebbe produrre il seguente output:
Record aggiornati: 10

Vedere anche: mysql_num_rows(), mysql_info().

mysql_change_user

(PHP 3 >= 3.0.13)

mysql_change_user -- Cambia l'utente della connessione attiva

Descrizione

int mysql_change_user ( string nome_utente, string password [, string database [, resource identificativo_connessione]] )

mysql_change_user() cambia l'utente dell'attuale connessione attiva o della connessione specificata dal parametro opzionale identificativo_connessione. Se un database is specificato, questo sarà il database corrente dopo che l'utente è stato cambiato. Se l'autorizzazione del nuovo utente e password falllisce, l'attuale utente connesso rimane attivo. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Nota: Questa funzione è stata introdotta nel PHP 3.0.13 e richiede MySQL 3.23.3 o successivo. Non è disponibile nel PHP 4.

mysql_client_encoding

(PHP 4 >= 4.3.0, PHP 5)

mysql_client_encoding -- Restituisce il nome del set di caratteri

Descrizione

int mysql_client_encoding ( [resource identificativo_connessione] )

mysql_client_encoding() restituisce il nome del set di caratteri predefinito per l'attuale connessione.

Esempio 1. Esempio di mysql_client_encoding()

<?php
$connessione = mysql_connect('localhost', 'utente_mysql', 'password_mysql');
$charset = mysql_client_encoding($connessione);
printf ("il set di carattei attuale è %s\n", $charset);
?>

L'esempio riportato sopra produce il seguente output:
il set di caratteri attuale è latin1

Vedere anche: mysql_real_escape_string()

mysql_close

(PHP 3, PHP 4, PHP 5)

mysql_close -- Chiude una connessione MySQL

Descrizione

bool mysql_close ( [resource identificativo_connessione] )

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

mysql_close() chiude la connessione al server MySQL associata all'identificativo di connessione specificato. Se identificativo_connessione non è specificato, viene usata l'ultima connessione aperta.

L'uso di mysql_close() non è normalmente necessario, dal momento che le connessioni non persistenti sono chiuse automaticamente alla fine dell'esecuzione dello script. Vedere anche freeing resources.

Nota: mysql_close() non chiude le connessioni persistenti create da mysql_pconnect().

Esempio 1. Esempio di chiura connessione MySQL

<?php
    $connessione = mysql_connect("localhost", "utente_mysql", "password_mysql")
        or die("Connessione non riuscita: " . mysql_error());
    print ("Connesso con successo");
    mysql_close($connessione);
?>

Vedere anche: mysql_connect(), e mysql_pconnect().

mysql_connect

(PHP 3, PHP 4, PHP 5)

mysql_connect -- Apre una connessione ad un server MySQL

Descrizione

resource mysql_connect ( [string server [, string nome_utente [, string password [, bool nuova_connessione [, int client_flags]]]]] )

Restituisce un identificativo di connessione MySQL in caso di successo oppure FALSE in caso di fallimento.

mysql_connect() stabilice una connessione ad un server MySQL. I seguenti valore predefiniti sono assunti per i parametri opzionali mancanti: server = 'localhost:3306', nome_utente = nome dell'utente proprietario del processo server e password = password vuota.

Il parametro server può anche includere un numero di porta. Es. "hostname:porta" o un percorso ad un socket es. ":/percorso/al/socket" per il localhost.

Nota: il supporto per ":porta" è stato aggiunto nel PHP 3.0B4.
Il supporto per ":/percorso/al/socket" è stato aggiunto nel PHP 3.0.10.
Si può eliminare il messaggio di errore nel caso di fallimento aggiungendo il prefisso @ al un nome della funzione.

Se si fa una seconda chiamata a mysql_connect() con gli stessi argomenti, nessuna nuova connessione sarà stabilita, ma sarà restituito l'identificativo della connessione già aperta. Il paramentro nuova_connessione modifica questo comportamento e fa sì che mysql_connect() apra sempre una nuova connessione, anche se mysql_connect() era stata chiamata prima con gli stessi parametri. il parametro client_flags può essere combinato con le costanti MYSQL_CLIENT_COMPRESS, MYSQL_CLIENT_IGNORE_SPACE o MYSQL_CLIENT_INTERACTIVE.

Nota: Il paramentro nuova_connessione è stato indrodotto dal PHP 4.2.0
Il parametro client_flags è stato introdotto dal PHP 4.3.0

La connessione al server sarà chiusa prima della fine dell'esecuzione dello script, a meno che questa non sia precedentemente chiusa esplicitamente richiamando mysql_close().

Esempio 1. Esempio di connessione MySQL

<?php
    $connessione = mysql_connect("localhost", "utente_mysql", "password_mysql")
        or die("Connessione non riuscita: " . mysql_error());
    print ("Connesso con successo");
    mysql_close($connessione);
?>

Vedere anche mysql_pconnect() e mysql_close().

mysql_create_db

(PHP 3, PHP 4, PHP 5)

mysql_create_db -- Crea un database MySQL

Descrizione

bool mysql_create_db ( string nome_database [, resource identificativo_connessione] )

mysql_create_db() tenta di creare un nuovo database nel server associato all'identificativo di conmnessione specificato.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempio 1. Esempio creazione database MySQL

<?php
    $connessione = mysql_pconnect("localhost", "utente_mysql", "password_mysql")
        or die("Connessione non riuscita: " . mysql_error());

    if (mysql_create_db("mio_db")) {
        print ("Database creato con successo\n");
    } else {
        printf ("Errore nella creazione del database: %s\n", mysql_error());
    }
?>

Per motivi di compatibilità con il passato, anche mysql_createdb() può essere usata. Questo è comunque sconsigliato.

Nota: La funzione mysql_create_db() è sconsigliata. Al suo posto è preferibile usare mysql_query() per inviare un'istruzione SQL CREATE DATABASE.

Vedere anche: mysql_drop_db(), mysql_query().

mysql_data_seek

(PHP 3, PHP 4, PHP 5)

mysql_data_seek -- Muove il puntatore interno del risultato

Descrizione

bool mysql_data_seek ( resource identificativo_risultato, int numero_riga )

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

mysql_data_seek() muove il puntatore di riga interno del risultato MySQL associato all'identificativo specificato per puntare ad un determinato numero di riga. La successiva chiamata a mysql_fetch_row() dovrebbe restituire questa riga.

numero_riga inizia da 0. numero_riga dovrebbe essere un valore nell'intervallo che va da 0 a mysql_num_rows - 1.

Nota: La funzione mysql_data_seek() può essere usata solo insieme a mysql_query(), non con mysql_unbuffered_query().

Esempio 1. Esempio seek dati MySQL

<?php
    $connessione = mysql_pconnect("localhost", "utente_mysql", "password_mysql")
        or die("Connessione non riuscita: " . mysql_error());

    mysql_select_db("samp_db")
        or die("Selezione del database non riuscita: " . mysql_error());

    $query = "SELECT cognome, nome FROM amici";
    $risultato = mysql_query($query)
        or die("Query fallita: " . mysql_error());

    /* caricamento righe in ordine inverso */
    for ($i = mysql_num_rows($risultato) - 1; $i >= 0; $i--) {
        if (!mysql_data_seek($risultato, $i)) {
            echo "Non si può eseguire il seek alla riga $i: " . mysql_error() . "\n";
            continue;
        }

        if(!($riga = mysql_fetch_object($risultato)))
            continue;

        echo "$riga->cognome $riga->nome<br />\n";
    }

    mysql_free_result($risultato);
?>

Vedere anche: mysql_query(), mysql_num_rows().

mysql_db_name

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

mysql_db_name -- Ottiene dei dati dal risultato

Descrizione

string mysql_db_name ( resource risultato, int riga [, mixed campo] )

mysql_db_name() accetta come primo paramentro il puntatore al risultato dalla chiamata a mysql_list_dbs(). Il parametro riga è un indice compreso nell'intervallo del risultato.

Se intercorre un errore, viene restituito FALSE. Usare mysql_errno() e mysql_error() per determinare la natura dell'errore.

Esempio 1. Esempio di mysql_db_name()

<?php
    error_reporting(E_ALL);

    mysql_connect('dbhost', 'nome_utente', 'password');
    $db_list = mysql_list_dbs();

    $i = 0;
    $conteggio = mysql_num_rows($lista_db);
    while ($i < $conteggio) {
        echo mysql_db_name($lista_db, $i) . "\n";
        $i++;
    }
?>

Per motivi di compatibilità con il passato, anche mysql_dbname() è è accettata. Questo comunque è sconsigliato.

mysql_db_query

(PHP 3, PHP 4, PHP 5)

mysql_db_query -- Invia una query MySQL

Descrizione

resource mysql_db_query ( string database, string query [, resource identificativo_connessione] )

Restituisce una risorsa risultato della query se è stato possibile eseguire quest'ultima, oppure FALSE in caso d'errore. La funzione restituisce TRUE/FALSE anche per le query INSERT/UPDATE/DELETE per indicarne il successo/fallimento.

mysql_db_query() seleziona un database ed esegue una query su di esso. Se l'identificativo di connessione opzionale non è specificato, la funzione proverà a cercare una connessione aperta al server MySQL e se tale connessione non viene trovata cercherà di crearne una come se mysql_connect() fosse chiamata senza argomenti.

Si informa che questa funzione NON commuta al database al quale si era connessi prima. in altre parole, non si può usare questa funzione per eseguire temporaneamente una query sql su un altro database, si deve commutare manualmente. Gli utenti sono fortemente incoraggiati ad usare la sintassi database.tabella nelle loro query sql in questa funzione.

Vedere anche mysql_connect() e mysql_query().

Nota: Questa funzione è stata sconsigliata a partire dal PHP 4.0.6. Non usare questa funzione.Usare invece mysql_select_db() e mysql_query().

mysql_drop_db

(PHP 3, PHP 4, PHP 5)

mysql_drop_db -- Elimina (cancella) un database MySQL

Descrizione

bool mysql_drop_db ( string nome_database [, resource identificativo_connessione] )

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

mysql_drop_db() tenta di eliminare (cancellare) un intero database dal server associato all'identificativo di connessione specificato.

Per motivi di compatibilità con il passato, anche mysql_dropdb() può essere usato. Questa è comunque sconsigliato.

Nota: La funzione mysql_drop_db() è sconsigliata. Al suo posto è preferibile usare mysql_query() per inviare una istruzione SQL DROP DATABASE.

Vedere anche: mysql_create_db(), mysql_query().

mysql_errno

(PHP 3, PHP 4, PHP 5)

mysql_errno -- Restituisce il valore numerico del messaggio di errore della precedente operazione MySQL

Descrizione

int mysql_errno ( [resource identificativo_connessione] )

Restituisce il numero di errore dall'ultima funzione MySQL, oppure 0 (zero) se nessun errore è intercorso.

Gli errori ritornano dal database MySQL senza visualizzare i messaggi di avvertimento. Usando invece mysql_errno() si recupera il codice di errore. Notare che questa funzione restituisce solo il codice errore della più recente funzione MySQL eseguita (ad esclusione di mysql_error() e mysql_errno()), quindi se la si vuole usare, assicurarsi di controllare il valore prima di richiamare un'altra funzione MySQL.
Esempio 1. Esempio di mysql_errno
<?php mysql_connect("localhost", "utente_mysql", "password_mysql"); mysql_select_db("db_inesistente"); echo mysql_errno() . ": " . mysql_error(). "\n"; mysql_select_db("kossu"); mysql_query("SELECT * FROM tabella_inesistente"); echo mysql_errno() . ": " . mysql_error() . "\n"; ?>
L'esempio riportato sopra dovrebbe produrre il seguente output:
1049: Unknown database 'db_inesistente' 1146: Table 'kossu.tabella_inesistente' doesn't exist

Nota: Se l'argomento opzionale è specificato la connessione indicata viene usata per recuperare il codice d'erroe. Altrimenti viene usata l'ultima connessione aperta.

Vedere anche: mysql_error()

mysql_error

(PHP 3, PHP 4, PHP 5)

mysql_error -- Restituisce il testo del messagio di errore della precedente operazione MySQL

Descrizione

string mysql_error ( [resource identificativo_connessione] )

Restituisce il testo dell'errore dall'ultima funzione MySQL, oppure '' (la stringa vuota) se nessun errore intercorre.

Gli errori ritornano dal database MySQL senza visualizzare i messaggi di avvertimento. Si usa invece mysql_error() per recuperare il testo dell'errore. Notare che questa funzione restituisce solo il testo dell'errore della più recente funzione MySQL eseguita (ad esclusione di mysql_error() e mysql_errno()), quindi se la si vuole usare, assicurarsi di controllare il valore prima di richiamare un'altra funzione MySQL.
Esempio 1. mysql_error Example
<?php mysql_connect("localhost", "utente_mysql", "password_mysql"); mysql_select_db("db_inesistente"); echo mysql_errno() . ": " . mysql_error(). "\n"; mysql_select_db("kossu"); mysql_query("SELECT * FROM tabella_inesistente"); echo mysql_errno() . ": " . mysql_error() . "\n"; ?>
L'esempio riportato sopra dovrebbe produrre il seguente output:
1049: Unknown database 'db_inesistente' 1146: Table 'kossu.tabella_inesistente' doesn't exist

Nota: Se l'argomento opzionale è specificato la connessione indicata viene usata per recuperare il codice d'erroe. Altrimenti viene usata l'ultima connessione aperta.

Vedere anche: mysql_errno()

mysql_escape_string

(PHP 4 >= 4.0.3, PHP 5)

mysql_escape_string -- Aggiunge le sequenze di escape in una stringa per l'uso in mysql_query.

Descrizione

string mysql_escape_string ( string stringa_senza_escape )

Questa funzione aggiunge le sequenze di escape a stringa_senza_escape, in modo che sia sicuro usarla in mysql_query().

Nota: mysql_escape_string() non aggiunge le sequenze di escape a % ed a _.
Questa funzione è identica a mysql_real_escape_string() eccetto che mysql_real_escape_string() accetta un identificativo di connessione ed aggiunge le sequenze di escape alla stringa in base al set di caratteri corrente. mysql_escape_string() non accetta come argomento un identificativo di connessione e non rispetta le impostazioni del corrente set di caratteri.

Esempio 1. Esempio di mysql_escape_string()

<?php
    $voce = "Zak's Laptop";
    $voce_con_escape = mysql_escape_string($voce);
    printf ("La stringa con le sequenze di escape: %s\n", $voce_con_escape);
?>

L'esempio riportato sopra dovrebbe produrre il seguente output:
La stringa con le sequenze di escape: Zak\'s Laptop

Vedere anche: mysql_real_escape_string(), addslashes(), e la direttiva magic_quotes_gpc .

mysql_fetch_array

(PHP 3, PHP 4, PHP 5)

mysql_fetch_array -- Carica una riga del risultato come un array associativo, un array numerico o entrambi.

Descrizione

array mysql_fetch_array ( resource risultato [, int tipo_risultato] )

Restituisce un array che corrisponde alla riga caricata o FALSE se non ci sono più righe.

mysql_fetch_array() è una versione estesa di mysql_fetch_row(). Oltre a memorizzare i dati del risultato in array con indice numerico, questa li memorizza anche con indici associativi usando i nomi dei campi come chiavi.

Se due o più colonne del risultato hanno gli stessi nomi di campo, l'ultima colonna avrà la precedenza. Per accedere alle altre colonne con lo stesso nome, si deve usare l'indice numerico della colonna o farne un alias. Per le colonne-alias, non si può accedere al contenuto con il nome della colonna originale (in questo esempio si usa 'campo').
Esempio 1. Query con nomi di campo duplicati
SELECT tabella1.campo as foo tabella2.campo as bar from tabella1, tabella2

Una cosa importante da notare è che l'uso di mysql_fetch_array() non è significativamente più lento dell'uso di mysql_fetch_row(); questo fornisce un significativo valore aggiunto.

Il secondo argomento opzionale tipo_risultato in mysql_fetch_array() è una costante e può assumere i seguenti valori: MYSQL_ASSOC, MYSQL_NUM e MYSQL_BOTH. Questa caratteristica è stata aggiunta nel PHP 3.0.7. MYSQL_BOTH è il valore predefinito per questo argomento.

Usando MYSQL_BOTH, si ottiene un array con entrambe gli indici (associativo e numerico). Usando MYSQL_ASSOC, si ottengono solo gli indici associativi (stesso funzionamento di mysql_fetch_assoc()), usando MYSQL_NUM, si ottengono solo gli indici numerici (stesso funzionamento di mysql_fetch_row()).

Nota: I nomi dei campi restituiti da questa funzione sono case-sensitive.

Esempio 2. mysql_fetch_array() con MYSQL_NUM
<?php mysql_connect("localhost", "utente_mysql", "password_mysql") or die("Connessione non riuscita: " . mysql_error()); mysql_select_db("mio_db"); $risultato = mysql_query("SELECT id, nome FROM mia_tabella"); while ($riga = mysql_fetch_array($risultato, MYSQL_NUM)) { printf ("ID: %s Nome: %s", $riga[0], $riga[1]); } mysql_free_result($risultato); ?>

Esempio 3. mysql_fetch_array() con MYSQL_ASSOC
<?php mysql_connect("localhost", "utente_mysql", "password_mysql") or die("Connessione non riuscita: " . mysql_error()); mysql_select_db("mio_db"); $risultato = mysql_query("SELECT id, nome FROM mia_tabella"); while ($riga = mysql_fetch_array($risultato, MYSQL_ASSOC)) { printf ("ID: %s Nome: %s", $riga["id"], $riga["name"]); } mysql_free_result($risultato); ?>

Esempio 4. mysql_fetch_array() con MYSQL_BOTH
<?php mysql_connect("localhost", "utente_mysql", "password_mysql") or die("Connessione non riuscita: " . mysql_error()); mysql_select_db("mio_db"); $risultato = mysql_query("SELECT id, nome FROM mia_tabella"); while ($riga = mysql_fetch_array($risultato, MYSQL_BOTH)) { printf ("ID: %s Nome: %s", $riga[0], $riga["nome"]); } mysql_free_result($risultato); ?>

Per maggiori dettagli, vedere anche mysql_fetch_row() e mysql_fetch_assoc().

mysql_fetch_assoc

(PHP 4 >= 4.0.3, PHP 5)

mysql_fetch_assoc -- Carica una riga del risultato come array associativo

Descrizione

array mysql_fetch_assoc ( resource risultato )

Restituisce un array associativo che corrisponde alla riga caricata o FALSE se non ci sono più righe.

mysql_fetch_assoc() è equivalente alla chiamata di mysql_fetch_array() con MYSQL_ASSOC come secondo parametro opzionale. Questa restituisce solo un array associativo. Questo è il modo incui mysql_fetch_array() funzionava originalmente. Se è necessario l'indice numerico al posto di quello associativo, usare mysql_fetch_array().

Se due o più colonne del risultato hanno gli stessi nomi di campo, l'ultima colonna avrà la precedenza. Per accedere alle altre colonne con lo stesso nome, si deve accedere al risultato con l'indice numerico usando mysql_fetch_row() oppure aggiunger degli alias. Vedere l'esempio nella descrizione di mysql_fetch_array() per quanto concerne gli alias.

Una cosa importante da notare è che l'uso di mysql_fetch_assoc() non è significativamente più lento dell'uso di mysql_fetch_row(); questo fornisce un significativo valore aggiunto.

Esempio 1. Un esteso esempio di mysql_fetch_assoc()

<?php

    $conn = mysql_connect("localhost", "utente_mysql", "password_mysql");

    if (!$conn) {
        echo "Impossibile connettersi al DB: " . mysql_error();
        exit;
    }

    if (!mysql_select_db("mio_nome_db")) {
        echo "Impossibile selezioanre mio_nome_db: " . mysql_error();
        exit;
    }

    $sql = "SELECT id as id_utente, nome_intero, stato_utente
            FROM   una_tabella
            WHERE  stato_utente = 1";

    $risultato = mysql_query($sql);

    if (!$risultato) {
        echo "Fallimento nell'esecuzione della query ($sql) dal DB: " . mysql_error();
        exit;
    }

    if (mysql_num_rows($risultato) == 0) {
        echo "Nessuna riga trovata, niente da stampare quindi si esce";
        exit;
    }

    // Finché esiste una riga di dati, si pone questa riga in $riga come un array associativo
    // Nota: Se ci si aspetta solo una riga, non è necessario usare un ciclo
    // Nota: Se si mette extract($riga); all'interno del seguente ciclo,
    //       si creeranno $id_utente, $nome_intero, and $stato_utente
    while ($riga = mysql_fetch_assoc($risultato)) {
        echo $riga["id_utente"];
        echo $riga["nome_intero"];
        echo $riga["stato_utente"];
    }

    mysql_free_result($risultato);

?>

Vedere anche mysql_fetch_row(), mysql_fetch_array(), mysql_query() e mysql_error().

mysql_fetch_field

(PHP 3, PHP 4, PHP 5)

mysql_fetch_field -- Ottiene informazioni sulla colonna da un risultato e le restituisce come oggetto

Descrizione

object mysql_fetch_field ( resource risultato [, int indice_campo] )

Restituisce un oggetto contenente le informazioni di un campo.

mysql_fetch_field() può essere usata al fine di ottenere informazioni circa i campi di un determinato risultato di una query. Se l'indice del campo non è specificato, il successivo campo non ancora recuperato da mysql_fetch_field() viene considerato.

Le proprietà dell'oggetto sono:

name - nome della colonna
table - nome della tabella a cui appartiene la colonna
max_length - massima lunghezza della colonna
not_null - 1 se la colonna non può essere NULL
primary_key - 1 se la colonna è una chiave primaria
unique_key - 1 se la colonna è una chiave unica
multiple_key - 1 se la colonna è una chiave non-unica
numeric - 1 se la colonna è numerica
blob - 1 se la colonna è un BLOB
type - il tipo della colonna
unsigned - 1 se la colonna è senza segno
zerofill - 1 se la colonna è completata da zeri

Esempio 1. mysql_fetch_field()

<?php
mysql_connect('localhost:3306', $utente, $password)
    or die("Connessione non riuscita: " . mysql_error());
mysql_select_db("database");
$risultato = mysql_query("select * from tabella")
    or die("Query fallita: " . mysql_error());
/* ottiene i metadata della colonna */
$i = 0;
while ($i < mysql_num_fields($risultato)) {
    echo "Informazioni della colonna $i:<br />\n";
    $meta = mysql_fetch_field($risultato);
    if (!$meta) {
        echo "Nessuna informazione disponibile<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($risultato);
?>

Vedere anche mysql_field_seek().

mysql_fetch_lengths

(PHP 3, PHP 4, PHP 5)

mysql_fetch_lengths -- Ottiene la lunghezza di ogni output nel risultato

Descrizione

array mysql_fetch_lengths ( resource risultato )

Restituisce un array che corrisponde alle lunghezze di ogni campo nell'ultima riga caricata da mysql_fetch_row() oppure FALSE in caso di errore.

mysql_fetch_lengths() memorizza le lunghezze di ogni colonna dell'ultima riga restituita da mysql_fetch_row(), mysql_fetch_array() e mysql_fetch_object() in un array, iniziando con un indice pari a 0.

Vedere anche: mysql_fetch_row().

mysql_fetch_object

(PHP 3, PHP 4, PHP 5)

mysql_fetch_object -- Carica una riga del risultato come un ogetto

Descrizione

object mysql_fetch_object ( resource risultato )

Restituisce un oggetto con proprietà che corrispondono alla riga caricata oppure FALSE se non ci sono più righe.

mysql_fetch_object() è simile a mysql_fetch_array(), con una differenza - viene restituito un oggetto invece che un array. Indirettamente, questo significa che si ha solo accesso ai dati attraverso i nomi dei campi e non attraverso il loro indice (i mumeri sono nomi di proprietà illeciti).

<?php /* questo è valido */ echo $riga->campo; /* questo non è valido */ echo $riga->0; ?>

In termini di velocità, la funzione è identica a mysql_fetch_array() e quasi veloce come mysql_fetch_row() (la differenza è insignificante).
Esempio 1. Esempio di mysql_fetch_object()
<?php mysql_connect("hostname", "utente", "password"); mysql_select_db($db); $risultato = mysql_query("select * from tabella"); while ($riga = mysql_fetch_object($risultato)) { echo $riga->id_utente; echo $riga->nome_intero; } mysql_free_result($risultato); ?>

Vedere anche: mysql_fetch_array() e mysql_fetch_row().

mysql_fetch_row

(PHP 3, PHP 4, PHP 5)

mysql_fetch_row -- Ottiene una riga del risultato come un array enumerato

Descrizione

array mysql_fetch_row ( resource risultato )

Restituisce un array che corrisponde ad una riga caricata oppure FALSE se non ci sono più righe.

mysql_fetch_row() carica una riga di dati dal risultato associato all'identificativo specificato. La riga è restituita com un array. Ogni colonna del risultato è memorizzata in un indice dell'array, partendo dall'indice 0.

La susseguente chiamata a mysql_fetch_row() restituisce la successiva riga nell'intervallo del risultato oppure FALSE se non ci sono più righe.

Vedere anche: mysql_fetch_array(), mysql_fetch_object(), mysql_data_seek(), mysql_fetch_lengths() e mysql_result().

mysql_field_flags

(PHP 3, PHP 4, PHP 5)

mysql_field_flags -- Ottine i flag associati al campo specificato di un risultato

Descrizione

string mysql_field_flags ( resource risultato, int indice_campo )

mysql_field_flags() restituisce i flag del campo specificato. I flag sono restituiti come singole parole per flag separate da un singolo spazio, in modo che sia possibile suddividere il valore restituito usando explode().

I seguenti flag sono restituiti, se la versione di MySQL è abbastanza aggiornata da supportarli: "not_null", "primary_key", "unique_key", "multiple_key", "blob", "unsigned", "zerofill", "binary", "enum", "auto_increment", "timestamp".

Per motivi di compatibilità con il passato, anche mysql_fieldflags() può essere usata. Questo comunque è sconsigliato.

mysql_field_len

(PHP 3, PHP 4, PHP 5)

mysql_field_len -- Restituisce la lunghezza del campo specificato

Descrizione

int mysql_field_len ( resource risultato, int indice_campo )

mysql_field_len() restituisce la lunghezza del campo specificato.

Per motivi di compatibilità con il passato, anche mysql_fieldlen() può essere usata. Questo comunque è sconsigliato.

mysql_field_name

(PHP 3, PHP 4, PHP 5)

mysql_field_name -- Ottiene il nome del campo specificato in un risultato

Descrizione

string mysql_field_name ( resource risultato, int indice_campo )

mysql_field_name() restituisce il nome del campo specificato dall'indice. risultato deve essere un identificativo di risultato valido e indice_campo è lo spiazzamento numerico del campo.

Nota: indice_campo inizia da 0.
Es. L'indice del terzo campo è in realtà 2, l'indice del quarto campo è 3 e così via.

mysql_free_result() libera utuuta la memoria associata all'identificativo del risultato risultato.

mysql_free_result() deve essere richiamata solo se si è preoccupati sulla quantità di memoria usata dalle query che restituiscono dei grandi risultati. Tutta la memoria associata al risultato è automaticamente liberata al termine dell'esecuzione dello script.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Per motivi di compatibilità con il passato, anche mysql_freeresult() può essere usata. Questo comunque è sconsigliato.

mysql_get_client_info

(PHP 4 >= 4.0.5, PHP 5)

mysql_get_client_info -- Ottine informazioni sul client MySQL

Descrizione

string mysql_get_client_info ( void )

mysql_get_client_info() restituisce una stringa che rappresenta la versione della libraria client.

Esempio 1. Esempio di mysql_get_client_info

<?php
    printf ("Informazioni sul client MySQL: %s\n", mysql_get_client_info());
?>

L'esempio riportato sopra dovrebbe produrre il seguente output:

Informazioni sul client MySQL: 3.23.39

Vedere anche: mysql_get_host_info(), mysql_get_proto_info() e mysql_get_server_info().

mysql_get_host_info

(PHP 4 >= 4.0.5, PHP 5)

mysql_get_host_info -- Ottiene le informazioni sull'host MySQL

Descrizione

string mysql_get_host_info ( [resource identificativo_connessione] )

mysql_get_host_info() restituisce una stringa che descrive il tipo di connessione in uso per identificativo_connessione, includendo il nome dell'host del server. Se identificativo_connessione è omesso, sarà usata l'ultima connessione aperta.

Esempio 1. Esempio di mysql_get_host_info

<?php
    mysql_connect("localhost", "utente_mysql", "password_mysql") or
        die("Connessione non riuscita: " . mysql_error());
    printf ("Informazioni sull'host MySQL: %s\n", mysql_get_host_info());
?>

L'esempio riportato sopra dovrebbe produrre il seguente output:

Informazioni sull'host MySQL: Localhost via UNIX socket

Vedere anche: mysql_get_client_info(), mysql_get_proto_info() e mysql_get_server_info().

mysql_get_proto_info

(PHP 4 >= 4.0.5, PHP 5)

mysql_get_proto_info -- Ottiene le informazion sul protocollo MySQL

Descrizione

int mysql_get_proto_info ( [resource identificativo_connessione] )

mysql_get_proto_info() restituisce la versione del protocollo usata dalla connessione identificativo_connessione. Se identificativo_connessione è omesso, sarà usata l'ultima connessione aperta.

Esempio 1. Esempio di mysql_get_proto_info

<?php
    mysql_connect("localhost", "utente_mysql", "password_mysql") or
        die("Connessione non riuscita: " . mysql_error());
    printf ("Versione del protocollo MySQL: %s\n", mysql_get_proto_info());
?>

L'esempio riportato sopra dovrebbe produrre il seguente output:

Versione del protocollo MySQL: 10

Vedere anche: mysql_get_client_info(), mysql_get_host_info() e mysql_get_server_info().

mysql_get_server_info

(PHP 4 >= 4.0.5, PHP 5)

mysql_get_server_info -- Ottiene le informazioni sul server MySQL

Descrizione

string mysql_get_server_info ( [resource identificativo_connessione] )

mysql_get_server_info() restituisce la versione del server usato dalla connessione identificativo_connessione. Se identificativo_connessione è omesso, sarà usata l'ultima connessione aperta.

Esempio 1. Esempio di mysql_get_server_info

<?php
    mysql_connect("localhost", "utente_mysql", "password_mysql") or
        die("Connessione non riuscita: " . mysql_error());
    printf ("Versione server MySQL: %s\n", mysql_get_server_info());
?>

L'esempio riportato sopra dovrebbe produrre il seguente output:

Versione server MySQL: 4.0.1-alpha

Vedere anche: mysql_get_client_info(), mysql_get_host_info() e mysql_get_proto_info().

mysql_info

(PHP 4 >= 4.3.0, PHP 5)

mysql_info -- Ottiene le informazioni relative alla query più recente.

Descrizione

string mysql_info ( [resource identificativo_connessione] )

mysql_info() restituisce informazioni dettagliate relative all'ultima query usando lo specifico identificativo_connessione. Se identificativo_connessione non è specificato, viene considerata l'ultima connessione aperta.

mysql_info() restituisce una stringa per tutte le istruzioni elencate di seguito. Per tutte le altre restituisce FALSE. Il formato della stringa dipende dall'istruzione data.
Esempio 1. Istruzioni MySQL significative
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
I numeri sono indicati solo a titolo esemplificativo; i loro valori corrispondono alla query.

Nota: mysql_info() restituisce un valore non FALSE per le istruzioni INSERT ... VALUES solo se nell'istruzione sono specificate liste di valori multipli.

Vedere anche: mysql_affected_rows()

mysql_insert_id

(PHP 3, PHP 4, PHP 5)

mysql_insert_id -- Ottiene l'identificativo generato dalla precedente operazione INSERT

Descrizione

int mysql_insert_id ( [resource identificativo_connessione] )

mysql_insert_id() restituisce l'identificativo generato per una colonna AUTO_INCREMENT dal precedente query INSERT usando lo specifico identificativo_connessione. Se identificativo_connessione non è specificato, viene considerata l'ultima connessione aperta.

mysql_insert_id() restituisce 0 se la precedente query non ha generato un valore AUTO_INCREMENT. Se è necessario salvare il valore per usarlo in seguito, assicurarsi di richiamare mysql_insert_id() immediatamente dopo la query che ha generato il valore.

Nota: Il valore della funzione SQL LAST_INSERT_ID() di MySQL contiene sempre il più recente valore AUTO_INCREMENT generato e non è azzerato dalle query.

Avvertimento

mysql_insert_id() converte il tipo restituito dalla funzione nativa dell'API C di MySQL mysql_insert_id() al tipo long (chiamata int nel PHP). Se la colonna AUTO_INCREMENT è del tipo BIGINT, il valore restituito da mysql_insert_id() sarà inesatto. In questo caso si usi la funzione SQL di MySQL LAST_INSERT_ID() in una query SQL.

Esempio 1. Esempio di mysql_insert_id

<?php
    mysql_connect("localhost", "utente_mysql", "password_mysql") or
        die("Connessione non riuscita: " . mysql_error());
    mysql_select_db("mio_db");

    mysql_query("INSERT INTO mia_tabella (prodotto) VALUES ('kossu')");
    printf ("L'ultimo recod inserito ha l'identificativo %d\n", mysql_insert_id());
?>

Vedere anche: mysql_query().

mysql_list_dbs

(PHP 3, PHP 4, PHP 5)

mysql_list_dbs -- Elenca i database disponibili in un server MySQL

Descrizione

resource mysql_list_dbs ( [resource identificativo_connessione] )

mysql_list_dbs() restituirà un risultato puntatore contenete i database resi disponibili dal demone mysql. Usare la funzione mysql_tablename() per esplorare questo risultato puntatore o qualsiasi funzione per i risultati delle tabelle, come mysql_fetch_array().

Esempio 1. Esempio di mysql_list_dbs()
<?php $connessione = mysql_connect('localhost', 'utente_mysql', 'password_mysql'); $lista_db = mysql_list_dbs($connessione); while ($riga = mysql_fetch_object($lista_db)) { echo $riga->Database . "\n"; } ?>
L'esempio riportato sopra dovrebbe produrre il seguente output:
database1 database2 database3 ...

Nota: Il codice riportato sopra dovrebbe funzionare facilmente con mysql_fetch_row() o altre funzioni simili.

Il parametro database è il nome del database da cui recuperare la lista di tabelle. in caso di errore, mysql_list_tables() restituisce FALSE.

Per motivi di compatibilità con il passato, anche mysql_listtables() può essere usata. Questo comunque è sconsigliato.

Esempio 1. mysql_list_tables() example

<?php
    $nome_db = 'nome_db_mysql';

    if (!mysql_connect('host_mysql', 'utente_mysql', 'password_mysql')) {
        print 'Connessione a mysql non riuscita';
        exit;
    }

    $risultato = mysql_list_tables($nome_db);

    if (!$risultato) {
        print "Errorore database, Impossibile elencare le tabelle\n";
        print 'Errore MySQL: ' . mysql_error();
        exit;
    }

    while ($riga = mysql_fetch_row($risultato)) {
        print "Tabella: $riga[0]\n";
    }

    mysql_free_result($risultato);
?>

Vedere anche: mysql_list_dbs() e mysql_tablename().

mysql_num_fields

(PHP 3, PHP 4, PHP 5)

mysql_num_fields -- Ottiene il numero di campi nel risultato

Descrizione

int mysql_num_fields ( resource risultato )

mysql_num_fields() restituisce il numero di campi in un risultato.

Vedere anche: mysql_select_db(), mysql_query(), mysql_fetch_field() e mysql_num_rows().

Per motivi di compatibilità con il passato, anche mysql_numfields() può essere usata. Questo comunque è sconsigliato.

mysql_num_rows

(PHP 3, PHP 4, PHP 5)

mysql_num_rows -- Ottiene il numero di righe in un risultato

Descrizione

int mysql_num_rows ( resource risultato )

mysql_num_rows() restituisce il numero di righe in un risultato. Questo comando è valido solo per le istruzioni SELECT. Per recuperare il numero di righe coinvolte dalle query INSERT, UPDATE o DELETE, usare mysql_affected_rows().
Esempio 1. Esempio di mysql_num_rows()
<?php $connessione = mysql_connect("localhost", "utente_mysql", "password_mysql"); mysql_select_db("database", $connessione); $risultato = mysql_query("SELECT * FROM tabella1", $connessione); $num_righe = mysql_num_rows($risultato); echo "$num_righe Righe\n"; ?>

Nota: Se si usa mysql_unbuffered_query(), mysql_num_rows() non restituirà il valore corretto finché non sono recuperate tutte le righe del risultato.

Vedere anche: mysql_affected_rows(), mysql_connect(), mysql_data_seek(), mysql_select_db() e mysql_query().

Per motivi di compatibilità con il passato, anche mysql_numrows() può essere usata. Questo comunque è sconsigliato.

mysql_pconnect

(PHP 3, PHP 4, PHP 5)

mysql_pconnect -- Apre una connessione persiostente ad un server MySQL

Descrizione

resource mysql_pconnect ( [string server [, string nome_utente [, string password [, int flag_client]]]] )

Restituisce un identificativo di connessione MySQL valido in caso di successo oppure FALSE in caso di errore.

mysql_pconnect() stabilisce una connessione ad un server MySQL. I seguenti valori predefiniti sono usati per i parametri opzionali mancanti: server = 'localhost:3306', nome_utente = nome dell'utente prprietario del processo server e password = password vuota. Il parametro flag_client può essere una combinatione delle costanti MYSQL_CLIENT_COMPRESS, MYSQL_CLIENT_IGNORE_SPACE o MYSQL_CLIENT_INTERACTIVE.

Il parametro server può includere una numero di porta. Es. "hostname:porta" o un percorso ad un socket es. ":/percorso/a/socket" per il localhost.

Nota: Il supporto per ":porta" è stato aggiunto nel PHP 3.0B4.
Il supportp per ":/percorso/a/socket" è stato aggiunto nel PHP 3.0.10.

mysql_pconnect() agisce in modo molto simile a mysql_connect() con due differenze principali.

Primo, quando si connette, la funzione tenta innanzitutto di trovare una connessione (persistente) già aperta avente gli stessi host, username e password. Se viene trovata una connessione, viene restituito un identificativo a questa anziché aprirne una nuova.

Secondo, la connessione al server SQL non sarà chiusa quando l'esecuzione dello script termina. La connessione rimane invece aperta per usi futuri (mysql_close() non chiuderà le connessioni stabilite da mysql_pconnect()).

Il parametro opzionale flag_client è diventato disponibile nel PHP 4.3.0.

Questo tipo di link è perciò chiamato 'persistente'.

Nota: Notare che questo tipo di connessione funziona solo se si usa PHP come modulo. Vedere la sezione Persistent Database Connections per maggiori informazioni.

Avvertimento

L'uso di connessioni persistenti può richiedere un po' di messa a punto delle configurazioni di Apache e MySQL per assicurarsi di non eccedere il numero di connessioni consentite da MySQL.

mysql_ping

(PHP 4 >= 4.3.0, PHP 5)

mysql_ping -- Esegue un ping su una connessione al server o riconnette se non non esiste la connessione

Descrizione

bool mysql_ping ( [resource identificativo_connessione] )

mysql_ping() controlla se una connessione al server funziona o meno. Se questa è caduta, viene tentata una riconnessione automatica. Questa funzione può essere usata dagli script che rimangono inattivi per un lungo periodo per controllare se il server ha chiuso la connessione o meno e riconnettersi se necessario. mysql_ping() restituisce TRUE se la connessione al server è funzionante, altrimenti FALSE.

Vedere anche: mysql_thread_id() e mysql_list_processes().

mysql_query

(PHP 3, PHP 4, PHP 5)

mysql_query -- Invia una query MySQL

Descrizione

resource mysql_query ( string query [, resource identificativo_connessione [, int modo_risultato]] )

mysql_query() invia una query al database attualmente attivo sul server associato all'identificativo di conmnessione specificato. Se identificativo_connessione non è specificato, viene considerata l'ultima connessione aperta. Se nessuna connessione è aperta, la funzione prova a stabilire una connessione come se mysql_connect() fosse richiamata senza argomenti ed usa questa.

Il paramentro opzionale modo_risultato può essere MYSQL_USE_RESULT e MYSQL_STORE_RESULT. Il valore predefinito MYSQL_STORE_RESULT, così il risultato è bufferato. Vedere anche mysql_unbuffered_query() per la controparte di questo comportamento.

Nota: La stringa della query non dovrebbe terminare con un punto e virgola.

Solo per le istruzioni SELECT, SHOW, EXPLAIN o DESCRIBE mysql_query() restituisce un identificativo di risorsa o FALSE se la query non è stata eseguita correttamente. Per altri tipi di istruzioni SQL, mysql_query() restituisce TRUE in caso di successo e FALSE in caso di errore. Un valore restituito diverso da FALSE indica che la query era lecita ed è stata eseguita dal server. Questo non indica niente riguardo il numero di righe coinvolte o restituite. è assolutamente possibile che una query abbia successo ma che non coinvolga o restituisca nessuna riga.

La seguente query non è valida sintatticamente, quindi mysql_query() fallisce e restituisce FALSE:
Esempio 1. mysql_query()
<?php $risultato = mysql_query("SELECT * WHERE 1=1") or die("Query non valida: " . mysql_error()); ?>

La seguente query non è semanticamente valida se mia_colonna non è una colonna della tabella mia_tabella, quindi mysql_query() fallisce e retituisce FALSE:
Esempio 2. mysql_query()
<?php $risultato = mysql_query("SELECT mia_colonna FROM mia_tabella") or die("Query non valida: " . mysql_error()); ?>

mysql_query() fallisce e restituisce FALSE anche se non si hanno i permessi per accedere alle tabelle cui la query fa riferimento.

Assumendo che la query abbia succeesso, si può richiamare mysql_num_rows() per scoprire quante righe sono state restituite da un'istruzione SELECT o mysql_affected_rows() per scoprire quante righe sono state coinvolte da un'istruzione DELETE, INSERT, REPLACE o UPDATE.

Solo per le istruzioni SELECT, SHOW, DESCRIBE o EXPLAIN, mysql_query() restituisce un nuovo identificativo di risultato che si può passare a mysql_fetch_array() e ad altre funzioni che si occupano dei risultati delle tabelle. Quando si conclude il trattamento del risultato, si possono liberare le risorse associate ad esso richiamando mysql_free_result(). Comunqe la memoria sarà liberata automaticamente Al termnine dell'esecuzione dello script.

Vedere anche: 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() e mysql_connect().

mysql_real_escape_string

(PHP 4 >= 4.3.0, PHP 5)

mysql_real_escape_string -- Aggiunge le sequenze di escape ai caratteri speciali in una stringa per l'uso in una istruzione SQL, tenendo conto dell'attuale set di caratteri della connessione.

Descrizione

string mysql_real_escape_string ( string stringa_seza_escape [, resource identificativo_connessione] )

Questa funzione aggiunge le sequenza di escape ai caratteri speciali in stringa_senza_escape, tenendo conto dell'attuale set di caratteri della connessione in modo che sia sicuro usarla in mysql_query().

Nota: mysql_real_escape_string() non aggiunge le sequenze di escape a % ed a _.

Esempio 1. Esempio di mysql_real_escape_string()

<?php
$connessione = mysql_connect('localhost', 'utente_mysql', 'password_mysql');
$voce = "Zak's and Derick's Laptop";
$voce_con_escape = mysql_real_escape_string($voce);
printf ("La stringa con le sequenze di escape: %s\n", $voce_con_escape);
?>

L'esempio riportato sopra dovrebbe produrre il seguente output:
La stringa con le sequenze di escape: Zak\'s and Derick\'s Laptop

Vedere anche : mysql_escape_string() e mysql_character_set_name().

mysql_result

(PHP 3, PHP 4, PHP 5)

mysql_result -- Ottiene i dati dal risultato

Descrizione

mixed mysql_result ( resource risultato, int campo [, mixed campo] )

mysql_result() restituisce i contenuti di una cella da un risultato MySQL. L'argomento campo può essere l'indice o il nome del campo oppure il nome della tabella ed il nome del campo separati da un punto (nome_tabella.nome_campo). Se il nome della colonna ha un alias ('select foo as bar from...'), usare l'alias al posto del nome della colonna.

Quando si lavora con un risultato di grandi dimensioni, si dovrebbero considerare l'uso delle funzioni che caricano l'intera riga (specificate di seguito). Poiché queste funzioni restituiscono i contenuti di celle multiple in una chiamata a funzione, sono MOLTO più veloci di mysql_result(). Notare anche che specificare un indice numerico per l'argomento campo è molto più veloce che specificare un argomento del tipo nome_di_campo o nome_tabella.nome_campo.

Le chiamate a mysql_result() non dovrebbero esserse mescolate con chiamate ad altre funzioni che hanno a che fare con i risultati.

Alternative raccomandate per alte prestazioni: mysql_fetch_row(), mysql_fetch_array() e mysql_fetch_object().

mysql_select_db

(PHP 3, PHP 4, PHP 5)

mysql_select_db -- Seleziona un database MySQL

Descrizione

bool mysql_select_db ( string nome_database [, resource identificativo_connessione] )

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

mysql_select_db() imposta il database attualmente attivo sul server associato all'identificativo di connessione specificato. Se nessin identificativo di connesione è specificato, viene considerata l'ultima connessione aperta. Se nessuna connessione è aperta, la funzione proverà a stabilire una connessione come se mysql_connect() fosse richiamata senza argomenti ed userà questa.

Ogni chiamata successiva a mysql_query() sarà fatta sul database attivo.

Vedere anche: mysql_connect(), mysql_pconnect() e mysql_query().

Per motivi di compatibilità con il passato, anche mysql_selectdb() può essere usata. Questo comunque è sconsigliato.

mysql_stat

(PHP 4 >= 4.3.0, PHP 5)

mysql_stat -- Ottiene l'attuale stato del sistema

Descrizione

string mysql_stat ( [resource identificativo_connessione] )

mysql_stat() restituisce l'attuale stato del server.

Nota: mysql_stat() attualmente restituisce solo le seguenti informazioni: uptime, thread, query, tabelle aperte, tabelle svuotate e query al secondo. Per una lista completa delle altre variabili di stato si usi il comando SQL SHOW STATUS.

Esempio 1. mysql_stat() example
<?php $connessione = mysql_connect('localhost', "utente_mysql", "password_mysql"); $stato = explode(' ', mysql_stat($connessione)); print_r($stato); ?>
L'esempio riportato sopra dovrebbe produrre il seguente output:
Array ( [0] => Uptime: 5380 [1] => Threads: 2 [2] => Questions: 1321299 [3] => Slow queries: 0 [4] => Opens: 26 [5] => Flush tables: 1 [6] => Open tables: 17 [7] => Queries per second avg: 245.595 )

mysql_tablename

(PHP 3, PHP 4, PHP 5)

mysql_tablename -- Ottiene il nome della tabella

Descrizione

string mysql_tablename ( resource risultato, int i )

mysql_tablename() prende il puntatore risultato dalla funzione mysql_list_tables() come un indice intero e restituisce il nome di una tabella. La funzione mysql_num_rows() può essere usata per determinare il numero di tabelle nel risultato puntatore. Usare la funzione mysql_tablename() per esplorare questo risultato puntatore o qualsiasi funzione per i risultati delle tabelle, come mysql_fetch_array().
Esempio 1. Esempio di mysql_tablename()
<?php mysql_connect("localhost", "utente_mysql", "password_mysql"); $risultato = mysql_list_tables("mio_db"); for ($i = 0; $i < mysql_num_rows($risultato); $i++) printf ("Tabela: %s\n", mysql_tablename($risultato, $i)); mysql_free_result($risultato); ?>

Vedere anche: mysql_list_tables().

mysql_thread_id

(PHP 4 >= 4.3.0, PHP 5)

mysql_thread_id -- Restituisce l'attuale thread ID

Descrizione

int mysql_thread_id ( [resource identificativo_connessione] )

mysql_thread_id() restituisce l'attuale thread ID. Se La connessione è persa a ci si riconnette con mysql_ping(), il thread ID cambia. Questo significa che non si dovrebbe ottenere il thread ID e memorizzarlo per impieghi successivi. Si dovrebbe rilevare il thread ID quando è necessario.

Esempio 1. Esempio di mysql_thread_id()

<?php
$connessione = mysql_connect('localhost', 'utente_mysql', 'password_mysql');
$thread_id = mysql_thread_id($connessione);
if ($thread_id){
    printf ("L'attuale thread è %d\n", $thread_id);
}
?>

L'esempio riportato sopra dovrebbe produrre il seguente output:
L'attuale thread è 73

Vedere anche: mysql_ping() e mysql_list_processes().

mysql_unbuffered_query

(PHP 4 >= 4.0.6, PHP 5)

mysql_unbuffered_query -- Invia una query SQL a MySQL senza caricare e bufferare le righe risultanti

Descrizione

resource mysql_unbuffered_query ( string query [, resource identificativo_connessione [, int modo_risultato]] )

mysql_unbuffered_query() invia una query SQL query a MySQL senza caricare e bufferare le righe risultanti automaticamente come fa mysql_query(). Da una parte, questo risparmia un considerevole quantità di memoria con le query SQL che producono risulati di grandi dimensioni. Dall'altra parte, si può iniziare l'elaborazione dei risultati immediatamente dopo che la prima riga è stata recuperata: non si deve attendere finché la query SQL sia completamente eseguita. Quando si usano diverse connessioni a database, si deve specificare il paramentro opzionale identificativo_connessione.

Il parametro opzionale modo_risultato può essere MYSQL_USE_RESULT e MYSQL_STORE_RESULT. Il valore predefinito è MYSQL_USE_RESULT, quindi il risultato non è bufferato. Vedere anche mysql_query() per la controparte di questo comportamento.

Nota: I benefici di mysql_unbuffered_query() hanno un costo: non si può usare mysql_num_rows() su un risultato restituito da mysql_unbuffered_query(). Inoltre si debbono caricare tutte le righe risultanti da una query SQL non bufferata prima di poter inviare una nuova query SQL a MySQL.

vedere anche: mysql_query().

LXXXVII. MySQL Functions (PDO_MYSQL)

Introduzione

PDO_MYSQL is a driver that implements the PHP Data Objects (PDO) interface to enable access from PHP to MySQL 3.x and 4.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.

Avvertimento

Beware: MySQL tables do not support transactions by default. When writing transactional database code, MySQL will pretend that a transaction was initiated successfully, even when no transactional support is present. In addition, any DDL queries issued will implicitly commit any pending transactions.

Costanti predefinite

The constants below are defined by this driver, and will only be available when the extension has been either compiled into PHP or dynamically loaded at runtime. In addition, these driver-specific constants should only be used if you are using this driver. Using mysql-specific attributes with the postgres driver may result in unexpected behaviour. PDO::getAttribute() may be used to obtain the PDO_ATTR_DRIVER_NAME attribute to check the driver, if your code can run against multiple drivers.

PDO_MYSQL_ATTR_USE_BUFFERED_QUERY (integer)

If this attribute is set to TRUE on 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.

Esempio 1. Forcing queries to be buffered in mysql
<?php if ($db->getAttribute(PDO_ATTR_DRIVERNAME) == 'mysql')) { $stmt = $db->prepare('select * from foo', array(PDO_MYSQL_ATTR_USE_UNBUFFERED_QUERY => true)); } else { die("my application only works with mysql; I should use \$stmt->fetchAll() instead"); }

Sommario
PDO_MYSQL DSN -- Connecting to MySQL databases

PDO_MYSQL DSN

(no version information, might be only in CVS)

PDO_MYSQL DSN -- Connecting to MySQL databases

Descrizione

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.
dbname: The name of the database.

Esempi

Esempio 1. PDO_MYSQL DSN examples
The following example shows a PDO_MYSQL DSN for connecting to MySQL databases:
mysql:host=localhost;dbname=testdb

LXXXVIII. MySQL Improved Extension

Introduzione

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/

Documentation for MySQL can be found at http://dev.mysql.com/doc/.

Parts of this documentation included from MySQL manual with permissions of MySQL AB.

Requisiti

In order to have these functions available, you must compile PHP with support for the mysqli extension.

Nota: The mysqli extension is designed to work with the version 4.1.3 or above of MySQL. For previous versions, please see the MySQL extension documentation.

Installazione

To install the mysqli extension for PHP, use the --with-mysqli=mysql_config_path/mysql_config configuration option where mysql_config_path represents the location of the mysql_config program that comes with MySQL versions greater than 4.1.

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.

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

Tabella 1. MySQLi Configuration Options

Name	Default	Changeable	Changelog
mysqli.max_links	"-1"	PHP_INI_SYSTEM	Available since PHP 5.0.0.
mysqli.default_port	"3306"	PHP_INI_ALL	Available since PHP 5.0.0.
mysqli.default_socket	NULL	PHP_INI_ALL	Available since PHP 5.0.0.
mysqli.default_host	NULL	PHP_INI_ALL	Available since PHP 5.0.0.
mysqli.default_user	NULL	PHP_INI_ALL	Available since PHP 5.0.0.
mysqli.default_pw	NULL	PHP_INI_ALL	Available since PHP 5.0.0.

For further details and definitions of the above PHP_INI_* constants, see the chapter on configuration changes.

Breve descrizione dei parametri di configurazione.

mysqli.max_links integer: The maximum number of MySQL connections per process.
mysqli.default_port string: 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_PORT constant, in that order. Win32 will only use the MYSQL_PORT constant.
mysqli.default_socket string: The default socket name to use when connecting to a local database server if no other socket name is specified.
mysqli.default_host string: The default server host to use when connecting to the database server if no other host is specified. Doesn't apply in safe mode.
mysqli.default_user string: The default user name to use when connecting to the database server if no other name is specified. Doesn't apply in safe mode.
mysqli.default_pw string: The default password to use when connecting to the database server if no other password is specified. Doesn't apply in safe mode.

Classi predefinite

mysqli

Represents a connection between PHP and a MySQL database.

Costruttori

mysqli - construct a new mysqli object

Metodi

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 MySQL 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 MySQL server
get_server_version - returns version of the MySQL server
init - initializes mysqli object
info - retrieves information about the most recently executed query
kill - asks the server to kill a mysql 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 a SQL query
query - performs a query
real_connect - attempts to open a connection to MySQL database server
escape_string - escapes special characters in a string for use in a SQL statement, taking into account the current charset of the connection
rollback - rolls back the current transaction
select_db - selects the default database
set_charset - sets the default client character set
ssl_set - sets ssl parameters
stat - gets the current system status
stmt_init- initializes a statement for use with mysqli_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

Proprietà

affected_rows - gets the number of affected rows in a previous MySQL operation
client_info - returns the MySQL client version as a string
client_version - returns the MySQL 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 MySQL protocol used
server_info - returns a string that represents the server version number
server_version - returns the version number of the server as an integer
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

mysqli_stmt

Represents a prepared statement.

Metodi

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 a SQL query
send_long_data - sends data in chunks
reset - resets a prepared statement
store_result - buffers complete resultset from a prepared statement

Proprietà

affected_rows - returns affected rows from last statement execution
errno - returns errorcode for last statement function
error - returns errormessage for last statement function
field_count - returns the number of columns in a result set
id - returns the statement identifier
insert_id - returns the value generated for an AUTO_INCREMENT column by the prepared statement
num_rows - returns the number of rows in the result set
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

mysqli_result

Represents the result set obtained from a query against the database.

Metodi

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

Proprietà

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
type - returns MYSQLI_STORE_RESULT or MYSQLI_USE_RESULT

Costanti predefinite

Tabella 2. MySQLi Constants

Name	Description
`MYSQLI_READ_DEFAULT_GROUP` (integer)	Read options from the named group from `my.cnf' or the file specified with `MYSQLI_READ_DEFAULT_FILE`
`MYSQLI_READ_DEFAULT_FILE` (integer)	Read options from the named option file instead of from `my.cnf`
`MYSQLI_OPT_CONNECT_TIMEOUT` (integer)	Connect timeout in seconds
`MYSQLI_OPT_LOCAL_INFILE` (integer)	Enables command `LOAD LOCAL INFILE`
`MYSQLI_INIT_COMMAND` (integer)	Command to execute when connecting to MySQL server. Will automatically be re-executed when reconnecting.
`MYSQLI_CLIENT_SSL` (integer)	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` (integer)	Use compression protocol
`MYSQLI_CLIENT_INTERACTIVE` (integer)	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` (integer)	Allow spaces after function names. Makes all functions names reserved words.
`MYSQLI_CLIENT_NO_SCHEMA` (integer)	Don't allow the db_name.tbl_name.col_name syntax.
`MYSQLI_CLIENT_MULTI_QUERIES` (integer)
`MYSQLI_STORE_RESULT` (integer)	For using buffered resultsets
`MYSQLI_USE_RESULT` (integer)	For using unbuffered resultsets
`MYSQLI_ASSOC` (integer)	Columns are returned into the array having the fieldname as the array index.
`MYSQLI_NUM` (integer)	Columns are returned into the array having an enumerated index.
`MYSQLI_BOTH` (integer)	Columns are returned into the array having both a numerical index and the fieldname as the associative index.
`MYSQLI_NOT_NULL_FLAG` (integer)	Indicates that a field is defined as `NOT NULL`
`MYSQLI_PRI_KEY_FLAG` (integer)	Field is part of a primary index
`MYSQLI_UNIQUE_KEY_FLAG` (integer)	Field is part of a unique index.
`MYSQLI_MULTIPLE_KEY_FLAG` (integer)	Field is part of an index.
`MYSQLI_BLOB_FLAG` (integer)	Field is defined as `BLOB`
`MYSQLI_UNSIGNED_FLAG` (integer)	Field is defined as `UNSIGNED`
`MYSQLI_ZEROFILL_FLAG` (integer)	Field is defined as `ZEROFILL`
`MYSQLI_AUTO_INCREMENT_FLAG` (integer)	Field is defined as `AUTO_INCREMENT`
`MYSQLI_TIMESTAMP_FLAG` (integer)	Field is defined as `TIMESTAMP`
`MYSQLI_SET_FLAG` (integer)	Field is defined as `SET`
`MYSQLI_NUM_FLAG` (integer)	Field is defined as `NUMERIC`
`MYSQLI_PART_KEY_FLAG` (integer)	Field is part of an multi-index
`MYSQLI_GROUP_FLAG` (integer)	Field is part of `GROUP BY`
`MYSQLI_TYPE_DECIMAL` (integer)	Field is defined as `DECIMAL`
`MYSQLI_TYPE_TINY` (integer)	Field is defined as `TINYINT`
`MYSQLI_TYPE_SHORT` (integer)	Field is defined as `INT`
`MYSQLI_TYPE_LONG` (integer)	Field is defined as `INT`
`MYSQLI_TYPE_FLOAT` (integer)	Field is defined as `FLOAT`
`MYSQLI_TYPE_DOUBLE` (integer)	Field is defined as `DOUBLE`
`MYSQLI_TYPE_NULL` (integer)	Field is defined as `DEFAULT NULL`
`MYSQLI_TYPE_TIMESTAMP` (integer)	Field is defined as `TIMESTAMP`
`MYSQLI_TYPE_LONGLONG` (integer)	Field is defined as `BIGINT`
`MYSQLI_TYPE_INT24` (integer)	Field is defined as `MEDIUMINT`
`MYSQLI_TYPE_DATE` (integer)	Field is defined as `DATE`
`MYSQLI_TYPE_TIME` (integer)	Field is defined as `TIME`
`MYSQLI_TYPE_DATETIME` (integer)	Field is defined as `DATETIME`
`MYSQLI_TYPE_YEAR` (integer)	Field is defined as `YEAR`
`MYSQLI_TYPE_NEWDATE` (integer)	Field is defined as `DATE`
`MYSQLI_TYPE_ENUM` (integer)	Field is defined as `ENUM`
`MYSQLI_TYPE_SET` (integer)	Field is defined as `SET`
`MYSQLI_TYPE_TINY_BLOB` (integer)	Field is defined as `TINYBLOB`
`MYSQLI_TYPE_MEDIUM_BLOB` (integer)	Field is defined as `MEDIUMBLOB`
`MYSQLI_TYPE_LONG_BLOB` (integer)	Field is defined as `LONGBLOB`
`MYSQLI_TYPE_BLOB` (integer)	Field is defined as `BLOB`
`MYSQLI_TYPE_VAR_STRING` (integer)	Field is defined as `VARCHAR`
`MYSQLI_TYPE_STRING` (integer)	Field is defined as `CHAR`
`MYSQLI_TYPE_GEOMETRY` (integer)	Field is defined as `GEOMETRY`
`MYSQLI_NEED_DATA` (integer)	More data available for bind variable
`MYSQLI_NO_DATA` (integer)	No more data available for bind variable
`MYSQLI_DATA_TRUNCATED` (integer)	Data truncation occurred. Available since PHP 5.1.0 and MySQL 5.0.5.

Examples

All Examples in the MySQLI documentation use the world database from MySQL AB. The world database can be found at http://dev.mysql.com/get/Downloads/Manual/world.sql.gz/from/pick

Sommario
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_bind_param -- Alias for mysqli_stmt_bind_param()
mysqli_bind_result -- Alias for mysqli_stmt_bind_result()
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_encoding -- Alias of mysqli_character_set_name()
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_connect -- Open a new connection to the MySQL server
mysqli_data_seek -- Adjusts the result pointer to an arbitary row in the result
mysqli_debug -- Performs debugging operations
mysqli_disable_reads_from_master -- Disable reads from master
mysqli_disable_rpl_parse -- Disable RPL parse
mysqli_dump_debug_info -- Dump debugging information into the log
mysqli_embedded_connect -- Open a connection to an embedded mysql server
mysqli_enable_reads_from_master -- Enable reads from master
mysqli_enable_rpl_parse -- Enable RPL parse
mysqli_errno -- Returns the error code for the most recent function call
mysqli_error -- Returns a string description of the last error
mysqli_escape_string -- Alias of mysqli_real_escape_string()
mysqli_execute -- Alias for mysqli_stmt_execute()
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_field_direct -- Fetch meta-data for a single field
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_fetch_lengths -- Returns the lengths of the columns of the current row in the result set
mysqli_fetch_object -- Returns the current row of a result set as an object
mysqli_fetch_row -- Get a result row as an enumerated array
mysqli_fetch -- Alias for mysqli_stmt_fetch()
mysqli_field_count -- Returns the number of columns for the most recent query
mysqli_field_seek -- Set result pointer to a specified field offset
mysqli_field_tell -- Get current field offset of a result pointer
mysqli_free_result -- Frees the memory associated with a result
mysqli_get_client_info -- Returns the MySQL client version as a string
mysqli_get_client_version -- Get MySQL client info
mysqli_get_host_info -- Returns a string representing the type of connection used
mysqli_get_metadata -- Alias for mysqli_stmt_result_metadata()
mysqli_get_proto_info -- Returns the version of the MySQL protocol used
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_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_master_query -- Enforce execution of a query on the master in a master/slave setup
mysqli_more_results -- Check if there 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_num_fields -- Get the number of fields in a result
mysqli_num_rows -- Gets the number of rows in a result
mysqli_options -- Set options
mysqli_param_count -- Alias for mysqli_stmt_param_count()
mysqli_ping -- Pings a server connection, or tries to reconnect if the connection has gone down
mysqli_prepare -- Prepare a 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 a SQL statement, taking into account the current charset of the connection
mysqli_real_query -- Execute an SQL query
mysqli_report -- Enables or disables internal report functions
mysqli_rollback -- Rolls back current transaction
mysqli_rpl_parse_enabled -- Check if RPL parse is enabled
mysqli_rpl_probe -- RPL probe
mysqli_rpl_query_type -- Returns RPL query type
mysqli_select_db -- Selects the default database for database queries
mysqli_send_long_data -- Alias for mysqli_stmt_send_long_data()
mysqli_send_query -- Send the query and return
mysqli_server_end -- Shut down the embedded server
mysqli_server_init -- Initialize embedded server
mysqli_set_charset -- Sets the default client character set
mysqli_set_opt -- Alias of mysqli_options()
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_affected_rows -- Returns the total number of rows changed, deleted, or inserted by the last executed 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 arbitray row in statement result set
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_execute -- Executes a prepared Query
mysqli_stmt_fetch -- Fetch results from a prepared statement into the bound variables
mysqli_stmt_free_result -- Frees stored result memory for the given statement handle
mysqli_stmt_init -- Initializes a statement and returns an object for use with mysqli_stmt_prepare
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 a 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_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_affected_rows

(PHP 5)

mysqli_affected_rows

(no version information, might be only in CVS)

mysqli->affected_rows -- Gets the number of affected rows in a previous MySQL operation

Description

Procedural style:

int mysqli_affected_rows ( mysqli link )

Object oriented style (property):

class mysqli {

int affected_rows

}

mysqli_affected_rows() returns the number of rows affected by the last INSERT, UPDATE, or DELETE query associated with the provided link parameter. If the last query was invalid, this function will return -1.

Nota: For SELECT statements mysqli_affected_rows() works like mysqli_num_rows().

The mysqli_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 mysqli_num_rows() function instead.

Valori restituiti

Nota: If the number of affected rows is greater than maximal int value, the number of affected rows will be returned as a string.

Vedere anche:

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

Affected rows (INSERT): 984
Affected rows (UPDATE): 168
Affected rows (DELETE): 815
Affected rows (SELECT): 169

mysqli_autocommit

(PHP 5)

mysqli_autocommit

(no version information, might be only in CVS)

mysqli->autocommit -- Turns on or off auto-commiting database modifications

Description

Procedural style:

bool mysqli_autocommit ( mysqli link, bool mode )

Object oriented style (method)

class mysqli {

bool autocommit ( bool mode )

}

mysqli_autocommit() is used to turn on or off auto-commit mode on queries for the database connection represented by the link object.

Nota: mysqli_autocommit() doesn't work with non transactional table types (like MyISAM or ISAM).
To determine the current state of autocommit use the SQL command 'SELECT @@autocommit'.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

mysqli_commit() e mysqli_rollback().

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

Autocommit is 1

mysqli_bind_param

(PHP 5)

mysqli_bind_param -- Alias for mysqli_stmt_bind_param()

Description

This function is an alias of mysqli_stmt_bind_param(). For a detailled descripton see description of mysqli_stmt_bind_param().

Nota: mysqli_bind_param() is deprecated and will be removed.

Vedere anche:

mysqli_stmt_bind_param().

mysqli_bind_result

(PHP 5)

mysqli_bind_result -- Alias for mysqli_stmt_bind_result()

Description

This function is an alias of mysqli_stmt_bind_result(). For a detailled descripton see description of mysqli_stmt_bind_result().

Nota: mysqli_bind_result() is deprecated and will be removed.

Vedere anche:

mysqli_stmt_bind_result().

mysqli_change_user

(PHP 5)

mysqli_change_user

(no version information, might be only in CVS)

mysqli->change_user -- Changes the user of the specified database connection

Description

Procedural style:

bool mysqli_change_user ( mysqli link, string user, string password, string database )

Object oriented style (method):

class mysqli {

bool change_user ( string user, string password, string database )

}

mysqli_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.

If desired, the NULL value may be passed in place of the database parameter resulting in only changing the user and not selecting a database. To select a database in this case use the mysqli_select_db() function.

Nota: 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.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

mysqli_connect() e mysqli_select_db().

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

Default database: world
Value of variable a is NULL

mysqli_character_set_name

(PHP 5)

mysqli_character_set_name

(no version information, might be only in CVS)

mysqli->character_set_name -- Returns the default character set for the database connection

Description

Procedural style:

string mysqli_character_set_name ( mysqli link )

Object oriented style (method):

class mysqli {

string character_set_name ( void )

}

Returns the current character set for the database connection specified by the link parameter.

Valori restituiti

The default character set for the current connection

Vedere anche:

mysqli_client_encoding() e mysqli_real_escape_string().

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

Current character set is latin1_swedish_ci

mysqli_client_encoding

(PHP 5)

mysqli_client_encoding -- Alias of mysqli_character_set_name()

Description

This function is an alias of mysqli_character_set_name(). For a detailled descripton see description of mysqli_character_set_name().

Vedere anche:

mysqli_real_escape_string().

mysqli_close

(PHP 5)

mysqli_close

(no version information, might be only in CVS)

mysqli->close -- Closes a previously opened database connection

Description

Procedural style:

bool mysqli_close ( mysqli link )

Object oriented style (method):

class mysqli {

bool close ( void )

}

The mysqli_close() function closes a previously opened database connection specified by the link parameter.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

mysqli_connect(), mysqli_init() e mysqli_real_connect().

mysqli_commit

(PHP 5)

mysqli_commit

(no version information, might be only in CVS)

mysqli->commit -- Commits the current transaction

Description

Procedural style:

bool mysqli_commit ( mysqli link )

Object oriented style (method)

class mysqli {

bool commit ( void )

}

Commits the current transaction for the database connection specified by the link parameter.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

mysqli_autocommit() e mysqli_rollback().

Esempi

Esempio 1. Object oriented style
<?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 Type=InnoDB"); /* 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(); ?>

Esempio 2. Procedural style
<?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 Type=InnoDB"); /* 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); ?>

mysqli_connect_errno

(PHP 5)

mysqli_connect_errno -- Returns the error code from last connect call

Description

int mysqli_connect_errno ( void )

The mysqli_connect_errno() function will return the last error code number for last call to mysqli_connect(). If no errors have occured, this function will return zero.

Nota: 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.

Valori restituiti

An error code value for the last call to mysqli_connect(), if it failed. zero means no error occurred.

Vedere anche:

mysqli_connect(), mysqli_connect_error(), mysqli_errno(), mysqli_error() e mysqli_sqlstate().

Esempi

Esempio 1. mysqli_connect_errno sample
<?php $link = @mysqli_connect("localhost", "nonexisting_user", ""); if (!$link) { printf("Can't connect to localhost. Errorcode: %d\n", mysqli_connect_errno()); } ?>

mysqli_connect_error

(PHP 5)

mysqli_connect_error -- Returns a string description of the last connect error

Description

string mysqli_connect_error ( void )

The mysqli_connect_error() function is identical to the corresponding mysqli_connect_errno() function in every way, except instead of returning an integer error code the mysqli_connect_error() function will return a string representation of the last error to occur for the last mysqli_connect() call. If no error has occured, this function will return an empty string.

Valori restituiti

A string that describes the error. An empty string if no error occurred.

Vedere anche:

mysqli_connect(), mysqli_connect_errno(), mysqli_errno(), mysqli_error() e mysqli_sqlstate().

Esempi

Esempio 1. mysqli_connect_error sample
<?php $link = @mysqli_connect("localhost", "nonexisting_user", ""); if (!$link) { printf("Can't connect to localhost. Error: %s\n", mysqli_connect_error()); } ?>

mysqli_connect

(PHP 5)

mysqli_connect

(no version information, might be only in CVS)

mysqli() -- Open a new connection to the MySQL server

Description

Procedural style

mysqli mysqli_connect ( [string host [, string username [, string passwd [, string dbname [, int port [, string socket]]]]]] )

Object oriented style (constructor):

class mysqli {

__construct ( [string host [, string username [, string passwd [, string dbname [, int port [, string socket]]]]]] )

}

The mysqli_connect() function attempts to open a connection to the MySQL Server running on host which 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. If successful, the mysqli_connect() will return an object representing the connection to the database, or FALSE on failure.

The username and password parameters specify the username and password under which to connect to the MySQL server. If the password is not provided (the NULL value is passed), 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).

The dbname parameter if provided will specify the default database to be used when performing queries.

The port and socket parameters are used in conjunction with the host parameter to further control how to connect to the database server. The port parameter specifies the port number to attempt to connect to the MySQL server on, while the socket parameter specifies the socket or named pipe that should be used.

Nota: Specifying the socket parameter 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 the host parameter.

Valori restituiti

Returns a object which represents the connection to a MySQL Server or FALSE if the connection failed.

Esempi

Esempio 1. Object oriented style

<?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("Host information: %s\n", $mysqli->host_info);

/* close connection */
$mysqli->close();
?>

Esempio 2. Procedural style

<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

/* check connection */ 
if (!$link) {
    printf("Connect failed: %s\n", mysqli_connect_error());
    exit();
}

printf("Host information: %s\n", mysqli_get_host_info($link));

/* close connection */
mysqli_close($link);
?>

Il precedente esempio visualizzerà:

Host information: Localhost via UNIX socket

mysqli_data_seek

(PHP 5)

mysqli_data_seek

(no version information, might be only in CVS)

result->data_seek -- Adjusts the result pointer to an arbitary row in the result

Description

Procedural style:

bool mysqli_data_seek ( mysqli_result result, int offset )

Object oriented style (method):

class mysqli_result {

bool data_seek ( int offset )

}

The mysqli_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..mysqli_num_rows() - 1).

Nota: This function can only be used with buffered results attained from the use of the mysqli_store_result() or mysqli_query() functions.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

mysqli_store_result(), mysqli_fetch_row(), mysqli_fetch_array(), mysqli_fetch_assoc(), mysqli_fetch_object(), mysqli_query() e mysqli_num_rows().

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

City: Benin City  Countrycode: NGA

mysqli_debug

(PHP 5)

mysqli_debug -- Performs debugging operations

Description

bool mysqli_debug ( string debug )

The mysqli_debug() function is used to perform debugging operations using the Fred Fish debugging library. The debug parameter is a string representing the debugging operation to perform.

Nota: To use the mysqli_debug() function you must complile the MySQL client library to support debugging.

Valori restituiti

mysqli_debug() doesn't return any value.

Vedere anche:

mysqli_dump_debug_info() e mysqli_report().

Esempi

Esempio 1. Generating a Trace File
<?php /* Create a trace file in '/tmp/client.trace' on the local (client) machine: */ mysqli_debug("d:t:0,/tmp/client.trace"); ?>

mysqli_disable_reads_from_master

(PHP 5)

mysqli_disable_reads_from_master

(no version information, might be only in CVS)

mysqli->disable_reads_from_master -- Disable reads from master

Description

Procedural style:

bool mysqli_disable_reads_from_master ( mysqli link )

Object oriented style (method):

class mysqli {

void disable_reads_from_master ( void )

}

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

mysqli_disable_rpl_parse

(PHP 5)

mysqli_disable_rpl_parse -- Disable RPL parse

Description

bool mysqli_disable_rpl_parse ( mysqli link )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

mysqli_dump_debug_info

(PHP 5)

mysqli_dump_debug_info

(no version information, might be only in CVS)

mysqli->dump_debug_info -- Dump debugging information into the log

Description

bool mysqli_dump_debug_info ( mysqli link )

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 specified by the link parameter.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

mysqli_debug().

mysqli_embedded_connect

(PHP 5 <= 5.0.4)

mysqli_embedded_connect -- Open a connection to an embedded mysql server

Description

mysqli mysqli_embedded_connect ( [string dbname] )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

mysqli_enable_reads_from_master

(PHP 5)

mysqli_enable_reads_from_master -- Enable reads from master

Description

bool mysqli_enable_reads_from_master ( mysqli link )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

mysqli_enable_rpl_parse

(PHP 5)

mysqli_enable_rpl_parse -- Enable RPL parse

Description

bool mysqli_enable_rpl_parse ( mysqli link )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

mysqli_errno

(PHP 5)

mysqli_errno

(no version information, might be only in CVS)

mysqli->errno -- Returns the error code for the most recent function call

Description

Procedural style:

int mysqli_errno ( mysqli link )

Object oriented style (property):

class mysqli {

int errno

}

The mysqli_errno() function will return the last error code for the most recent MySQLi 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.

Nota: 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.

Valori restituiti

An error code value for the last call, if it failed. zero means no error occurred.

Vedere anche:

mysqli_connect_errno(), mysqli_connect_error(), mysqli_error() e mysqli_sqlstate().

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

Errorcode: 1193

mysqli_error

(PHP 5)

mysqli_error -- Returns a string description of the last error

Description

Procedural style:

string mysqli_error ( mysqli link )

Object oriented style (property)

class mysqli {

string error

}

The mysqli_error() function is identical to the corresponding mysqli_errno() function in every way, except instead of returning an integer error code the mysqli_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.

Valori restituiti

A string that describes the error. An empty string if no error occurred.

Vedere anche:

mysqli_connect_errno(), mysqli_connect_error(), mysqli_errno() e mysqli_sqlstate().

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

Errormessage: Unknown system variable 'a'

mysqli_escape_string

(PHP 5)

mysqli_escape_string -- Alias of mysqli_real_escape_string()

Description

This function is an alias of mysqli_real_escape_string().

mysqli_execute

(PHP 5)

mysqli_execute -- Alias for mysqli_stmt_execute()

Description

This function is an alias of mysqli_stmt_execute(). For a detailled descripton see description of mysqli_stmt_execute().

Nota: mysqli_execute() is deprecated and will be removed.

Vedere anche:

mysqli_stmt_execute().

mysqli_fetch_array

(PHP 5)

mysqli_fetch_array

(no version information, might be only in CVS)

result->fetch_array -- Fetch a result row as an associative, a numeric array, or both

Description

Procedural style:

mixed mysqli_fetch_array ( mysqli_result result [, int resulttype] )

Object oriented style (method):

class mysqli_result {

mixed fetch_array ( [int resulttype] )

}

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.

Nota: I nomi dei campi restituiti da questa funzione sono case-sensitive.

Nota: This function sets NULL fields to PHP NULL value.

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 MYSQLI_ASSOC, MYSQLI_NUM, or MYSQLI_BOTH. By default the mysqli_fetch_array() function will assume MYSQLI_BOTH for this parameter.

By using the MYSQLI_ASSOC constant this function will behave identically to the mysqli_fetch_assoc(), while MYSQLI_NUM will behave identically to the mysqli_fetch_row() function. The final option MYSQLI_BOTH will create a single array with the attributes of both.

Valori restituiti

Returns an array that corresponds to the fetched row or NULL if there are no more rows in resultset.

Vedere anche:

mysqli_fetch_assoc(), mysqli_fetch_row(), mysqli_fetch_object(), mysqli_query() e mysqli_data_seek().

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

Kabul (AFG)
Qandahar (AFG)
Herat (AFG)

mysqli_fetch_assoc

(PHP 5)

mysqli_fetch_assoc

(no version information, might be only in CVS)

mysqli->fetch_assoc -- Fetch a result row as an associative array

Description

Procedural style:

array mysqli_fetch_assoc ( mysqli_result result )

Object oriented style (method):

class mysqli_result {

array fetch_assoc ( void )

}

Returns an associative array that corresponds to the fetched row or NULL if there are no more rows.

The mysqli_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.

Nota: I nomi dei campi restituiti da questa funzione sono case-sensitive.

Nota: This function sets NULL fields to PHP NULL value.

Valori restituiti

Returns an array that corresponds to the fetched row or NULL if there are no more rows in resultset.

Vedere anche:

mysqli_fetch_array(), mysqli_fetch_row(), mysqli_fetch_object(), mysqli_query() e mysqli_data_seek().

Esempi

Esempio 1. Object oriented style

<?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->close();
}

/* close connection */
$mysqli->close();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

Pueblo (USA)
Arvada (USA)
Cape Coral (USA)
Green Bay (USA)
Santa Clara (USA)

mysqli_fetch_field_direct

(PHP 5)

mysqli_fetch_field_direct

(no version information, might be only in CVS)

result->fetch_field_direct -- Fetch meta-data for a single field

Description

Procedural style:

object mysqli_fetch_field_direct ( mysqli_result result, int fieldnr )

Object oriented style (method):

class mysqli_result {

object fetch_field_direct ( int fieldnr )

}

mysqli_fetch_field_direct() returns an object which contains field definition informations from specified resultset. The value of fieldnr must be in the range from 0 to number of fields - 1.

Valori restituiti

Returns an object which contains field definition information or FALSE if no field information for specified fieldnr is available.

Tabella 1. Object attributes

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.
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)

Vedere anche:

mysqli_num_fields(), mysqli_fetch_field() e mysqli_fetch_fields().

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

Name:     SurfaceArea
Table:    Country
max. Len: 10
Flags:    32769
Type:     4

mysqli_fetch_field

(PHP 5)

mysqli_fetch_field

(no version information, might be only in CVS)

result->fetch_field -- Returns the next field in the result set

Description

Procedural style:

object mysqli_fetch_field ( mysqli_result result )

Object oriented style (method):

class mysqli_result {

object fetch_field ( void )

}

The mysqli_fetch_field() 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. mysqli_fetch_field() returns FALSE when no more fields are left.

Valori restituiti

Returns an object which contains field definition information or FALSE if no field information is available.

Tabella 1. Object properties

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	The default value for this field, represented as a string
max_length	The maximum width of the field for the result set.
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)

Vedere anche:

mysqli_num_fields(), mysqli_fetch_field_direct(), mysqli_fetch_fields() e mysqli_field_seek().

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

Name:     Name
Table:    Country
max. Len: 11
Flags:    1
Type:     254

Name:     SurfaceArea
Table:    Country
max. Len: 10
Flags:    32769
Type:     4

mysqli_fetch_fields

(PHP 5)

mysqli_fetch_fields

(no version information, might be only in CVS)

result->fetch_fields -- Returns an array of objects representing the fields in a result set

Description

Procedural Style:

array mysqli_fetch_fields ( mysqli_result result )

Object oriented style (method):

class mysqli_result {

array fetch_fields ( void )

}

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.

Valori restituiti

Returns an array of objects which contains field definition information or FALSE if no field information is available.

Tabella 1. Object properties

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	The default value for this field, represented as a string
max_length	The maximum width of the field for the result set.
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)

Vedere anche:

mysqli_num_fields(), mysqli_fetch_field() e mysqli_fetch_field_direct().

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

Name:     Name
Table:    Country
max. Len: 11
Flags:    1
Type:     254

Name:     SurfaceArea
Table:    Country
max. Len: 10
Flags:    32769
Type:     4

mysqli_fetch_lengths

(PHP 5)

mysqli_fetch_lengths

(no version information, might be only in CVS)

result->lengths -- Returns the lengths of the columns of the current row in the result set

Description

Procedural style:

array mysqli_fetch_lengths ( mysqli_result result )

Object oriented style (property):

class mysqli_result {

array lengths

}

The mysqli_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 or FALSE on failure.

Valori restituiti

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.

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

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_fetch_object

(PHP 5)

mysqli_fetch_object

(no version information, might be only in CVS)

result->fetch_object -- Returns the current row of a result set as an object

Description

Procedural style:

mixed mysqli_fetch_object ( mysqli_result result )

Object oriented style (method):

class mysqli_result {

mixed fetch_object ( void )

}

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. If no more rows exist in the current result set, NULL is returned.

Valori restituiti

Returns an object that corresponds to the fetched row or NULL if there are no more rows in resultset.

Nota: I nomi dei campi restituiti da questa funzione sono case-sensitive.

Nota: This function sets NULL fields to PHP NULL value.

Vedere anche:

mysqli_fetch_array(), mysqli_fetch_assoc(), mysqli_fetch_row(), mysqli_query() e mysqli_data_seek().

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

Pueblo (USA)
Arvada (USA)
Cape Coral (USA)
Green Bay (USA)
Santa Clara (USA)

mysqli_fetch_row

(PHP 5)

mysqli_fetch_row

(no version information, might be only in CVS)

result->fetch_row -- Get a result row as an enumerated array

Description

Procedural style:

mixed mysqli_fetch_row ( mysqli_result result )

Object oriented style (method):

class mysqli_result {

mixed fetch_row ( void )

}

Returns an array that corresponds to the fetched row, or NULL if there are no more rows.

mysqli_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 mysqli_fetch_row() function will return the next row within the result set, or FALSE if there are no more rows.

Valori restituiti

mysqli_fetch_row() returns an array that corresponds to the fetched row or NULL if there are no more rows in result set.

Nota: This function sets NULL fields to PHP NULL value.

Vedere anche:

mysqli_fetch_array(), mysqli_fetch_assoc(), mysqli_fetch_object(), mysqli_query() e mysqli_data_seek().

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

Pueblo (USA)
Arvada (USA)
Cape Coral (USA)
Green Bay (USA)
Santa Clara (USA)

mysqli_fetch

(PHP 5)

mysqli_fetch -- Alias for mysqli_stmt_fetch()

Description

This function is an alias of mysqli_stmt_fetch(). For a detailled descripton see description of mysqli_stmt_fetch().

Nota: mysqli_fetch() is deprecated and will be removed.

Vedere anche:

mysqli_stmt_fetch().

mysqli_field_count

(PHP 5)

mysqli_field_count

(no version information, might be only in CVS)

mysqli->field_count -- Returns the number of columns for the most recent query

Description

Procedural style:

int mysqli_field_count ( mysqli link )

Object oriented style (method):

class mysqli_result {

int field_count ( void )

}

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.

Valori restituiti

An integer representing the number of fields in a result set

Esempi

Esempio 1. Object oriented style
<?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($HTTP_POST_VARS['query']); if (mysqli_field_count($link)) { /* 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(); ?>

Esempio 2. Procedural style
<?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, $HTTP_POST_VARS['query']); 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_field_seek

(PHP 5)

mysqli_field_seek

(no version information, might be only in CVS)

result->field_seek -- Set result pointer to a specified field offset

Description

Procedural style:

bool mysqli_field_seek ( mysqli_result result, int fieldnr )

Object oriented style (method):

class mysqli_result {

bool field_seek ( int fieldnr )

}

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.

Nota: To seek to the beginning of a row, pass an offset value of zero.

Valori restituiti

mysqli_field_seek() returns previuos value of field cursor.

Vedere anche:

mysqli_fetch_field().

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

Name:     SurfaceArea
Table:    Country
max. Len: 10
Flags:    32769
Type:     4

mysqli_field_tell

(PHP 5)

mysqli_field_tell

(no version information, might be only in CVS)

result->current_field -- Get current field offset of a result pointer

Description

Procedural style:

int mysqli_field_tell ( mysqli_result result )

Object oriented style (property):

class mysqli_result {

int current_field

}

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().

Valori restituiti

Returns current offset of field cursor.

Vedere anche:

mysqli_fetch_field() e mysqli_field_seek().

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

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

mysqli_free_result

(PHP 5)

mysqli_free_result

(no version information, might be only in CVS)

result->free -- Frees the memory associated with a result

Description

Procedural style:

void mysqli_free_result ( mysqli_result result )

Object oriented style (method):

class mysqli_result {

void free ( void )

}

The mysqli_free_result() function frees the memory associated with the result represented by the result parameter, which was allocated by mysqli_query(), mysqli_store_result() or mysqli_use_result().

Nota: You should always free your result with mysqli_free_result(), when your result object is not needed anymore.

Valori restituiti

This function doesn't return any value.

Vedere anche:

mysqli_query(), mysqli_stmt_store_result(), mysqli_store_result() e mysqli_use_result().

mysqli_get_client_info

(PHP 5)

mysqli_get_client_info -- Returns the MySQL client version as a string

Description

string mysqli_get_client_info ( void )

The mysqli_get_client_info() function is used to return a string representing the client version being used in the MySQLi extension.

Valori restituiti

A string that represents the MySQL client library version

Vedere anche:

mysqli_get_client_version(), mysqli_get_server_info() e mysqli_get_server_version().

Esempi

Esempio 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()); ?>

mysqli_get_client_version

(PHP 5)

mysqli_get_client_version -- Get MySQL client info

Description

int mysqli_get_client_version ( void )

Returns client version number as an integer.

Valori restituiti

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.

Vedere anche:

mysqli_get_client_info(), mysqli_get_server_info() e mysqli_get_server_version().

Esempi

Esempio 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()); ?>

mysqli_get_host_info

(PHP 5)

mysqli_get_host_info

(no version information, might be only in CVS)

mysqli->get_host_info -- Returns a string representing the type of connection used

Description

Procdural style:

string mysqli_get_host_info ( mysqli link )

Object oriented style (property):

class mysqli {

string host_info

}

The mysqli_get_host_info() function returns a string describing the connection represented by the link parameter is using (including the server host name).

Valori restituiti

A character string representing the server hostname and the connection type.

Vedere anche:

mysqli_get_proto_info().

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

Host info: Localhost via UNIX socket

mysqli_get_metadata

(PHP 5)

mysqli_get_metadata -- Alias for mysqli_stmt_result_metadata()

Description

This function is an alias of mysqli_stmt_result_metadata(). For a detailled descripton see description of mysqli_stmt_result_metadata().

Nota: mysqli_get_metadata() is deprecated and will be removed.

Vedere anche:

mysqli_stmt_result_metadata().

mysqli_get_proto_info

(PHP 5)

mysqli_get_proto_info

(no version information, might be only in CVS)

mysqli->protocol_version -- Returns the version of the MySQL protocol used

Description

Procedural style:

int mysqli_get_proto_info ( mysqli link )

Object oriented style (property):

class mysqli {

string protocol_version

}

Returns an integer representing the MySQL protocol version used by the connection represented by the link parameter.

Valori restituiti

Returns an integer representing the protocol version.

Vedere anche:

mysqli_get_host_info().

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

Protocol version: 10

mysqli_get_server_info

(PHP 5)

mysqli_get_server_info

(no version information, might be only in CVS)

mysqli->server_info -- Returns the version of the MySQL server

Description

Procedural style:

string mysqli_get_server_info ( mysqli link )

Object oriented style (property):

class mysqli {

string server_info

}

Returns a string representing the version of the MySQL server that the MySQLi extension is connected to (represented by the link parameter).

Valori restituiti

A character string representing the server version.

Vedere anche:

mysqli_get_client_info(), mysqli_get_client_version() e mysqli_get_server_version().

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

Server version: 4.1.2-alpha-debug

mysqli_get_server_version

(PHP 5)

mysqli_get_server_version -- Returns the version of the MySQL server as an integer

Description

Procedural style:

int mysqli_get_server_version ( mysqli link )

Object oriented style (property):

class mysqli {

int server_version

}

The mysqli_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 4.1.0 is 40100).

Valori restituiti

An integer representing the server version.

Vedere anche:

mysqli_get_client_info(), mysqli_get_client_version() e mysqli_get_server_info().

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

Server version: 40102

mysqli_info

(PHP 5)

mysqli_info

(no version information, might be only in CVS)

mysqli->info -- Retrieves information about the most recently executed query

Description

Procedural style:

string mysqli_info ( mysqli link )

Object oriented style (property)

class mysqli {

string info

}

The mysqli_info() function returns a string providing information about the last query executed. The nature of this string is provided below:

Tabella 1. Possible mysqli_info return values

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

Nota: Queries which do not fall into one of the above formats are not supported. In these situations, mysqli_info() will return an empty string.

Valori restituiti

A character string representing additional information about the most recently executed query.

Vedere anche:

mysqli_affected_rows(), mysqli_warning_count() e mysqli_num_rows().

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

Records: 150  Duplicates: 0  Warnings: 0

mysqli_init

(PHP 5)

mysqli_init -- Initializes MySQLi and returns a resource for use with mysqli_real_connect()

Description

mysqli mysqli_init ( void )

Allocates or initializes a MYSQL object suitable for mysqli_options() and mysqli_real_connect().

Nota: Any subsequent calls to any mysqli function (except mysqli_options()) will fail until mysqli_real_connect() was called.

Valori restituiti

Returns an object.

Vedere anche:

mysqli_options(), mysqli_close(), mysqli_real_connect() e mysqli_connect().

mysqli_insert_id

(PHP 5)

mysqli_insert_id

(no version information, might be only in CVS)

mysqli->insert_id -- Returns the auto generated id used in the last query

Description

Procedural style:

int mysqli_insert_id ( mysqli link )

Object oriented style (property):

class mysqli {

int insert_id

}

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.

Nota: Performing an INSERT or UPDATE statement using the LAST_INSERT_ID() function will also modify the value returned by the mysqli_insert_id() function.

Valori restituiti

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.

Nota: If the number is greater than maximal int value, mysqli_insert_id() will return a string.

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

New Record has id 1.

mysqli_kill

(PHP 5)

mysqli_kill

(no version information, might be only in CVS)

mysqli->kill -- Asks the server to kill a MySQL thread

Description

Procedural style:

bool mysqli_kill ( mysqli link, int processid )

Object oriented style (method)

class mysqli {

bool kill ( int processid )

}

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.

Nota: To stop a running query you should use the SQL command KILL QUERY processid.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

mysqli_thread_id().

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

Error: MySQL server has gone away

mysqli_master_query

(PHP 5)

mysqli_master_query -- Enforce execution of a query on the master in a master/slave setup

Description

bool mysqli_master_query ( mysqli link, string query )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

mysqli_more_results

(PHP 5)

mysqli_more_results

(no version information, might be only in CVS)

mysqli->more_results -- Check if there any more query results from a multi query

Description

bool mysqli_more_results ( mysqli link )

mysqli_more_results() indicates if one or more result sets are available from a previous call to mysqli_multi_query().

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

mysqli_multi_query(), mysqli_next_result(), mysqli_store_result() e mysqli_use_result().

Esempi

See mysqli_multi_query().

mysqli_multi_query

(PHP 5)

mysqli_multi_query

(no version information, might be only in CVS)

mysqli->multi_query -- Performs a query on the database

Description

Procedural style:

bool mysqli_multi_query ( mysqli link, string query )

Object oriented style (method):

class mysqli {

bool multi_query ( string query )

}

The mysqli_multi_query() 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().

Valori restituiti

mysqli_multi_query() only returns FALSE if the first statement failed. To retrieve subsequent errors from other statements you have to call mysqli_next_result() first.

Vedere anche:

mysqli_use_result(), mysqli_store_result(), mysqli_next_result() e mysqli_more_results().

Esempi

Esempio 1. Object oriented style

<?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->close();
        }
        /* print divider */
        if ($mysqli->more_results()) {
            printf("-----------------\n");
        }
    } while ($mysqli->next_result());
}

/* close connection */
$mysqli->close();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

my_user@localhost
-----------------
Amersfoort
Maastricht
Dordrecht
Leiden
Haarlemmermeer

mysqli_next_result

(PHP 5)

mysqli_next_result

(no version information, might be only in CVS)

mysqli->next_result -- Prepare next result from multi_query

Description

bool mysqli_next_result ( mysqli link )

mysqli_next_result() prepares next result set from a previous call to mysqli_multi_query() which can be retrieved by mysqli_store_result() or mysqli_use_result().

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

mysqli_multi_query(), mysqli_more_results(), mysqli_store_result() e mysqli_use_result().

Esempi

See mysqli_multi_query().

mysqli_num_fields

(PHP 5)

mysqli_num_fields

(no version information, might be only in CVS)

result->field_count -- Get the number of fields in a result

Description

Procedural style:

int mysqli_num_fields ( mysqli_result result )

Object oriented style (property):

class mysqli_result {

int field_count

}

mysqli_num_fields() returns the number of fields from specified result set.

Valori restituiti

The number of fields from a result set

Vedere anche:

mysqli_fetch_field().

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

Result set has 5 fields.

mysqli_num_rows

(PHP 5)

mysqli_num_rows -- Gets the number of rows in a result

Description

Procedural style:

int mysqli_num_rows ( mysqli result )

Object oriented style (property):

class mysqli {

int num_rows

}

Returns the number of rows in the result set.

The use of mysqli_num_rows() depends on whether you use buffered or unbuffered result sets. In case you use unbuffered resultsets mysqli_num_rows() will not correct the correct number of rows until all the rows in the result have been retrieved.

Valori restituiti

Returns number of rows in the result set.

Nota: If the number of rows is greater than maximal int value, the number will be returned as a string.

Vedere anche:

mysqli_affected_rows(), mysqli_store_result(), mysqli_use_result() e mysqli_query().

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

Result set has 239 rows.

mysqli_options

(PHP 5)

mysqli_options

(no version information, might be only in CVS)

mysqli->options -- Set options

Description

Procedural style:

bool mysqli_options ( mysqli link, int option, mixed value )

Object oriented style (method)

class mysqli {

bool options ( int option, mixed value )

}

mysqli_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.

mysqli_options() should be called after mysqli_init() and before mysqli_real_connect().

The parameter option is the option that you want to set, the value is the value for the option. The parameter option can be one of the following values:

Tabella 1. Valid options

Name	Description
`MYSQLI_OPT_CONNECT_TIMEOUT`	connection timeout in seconds
`MYSQLI_OPT_LOCAL_INFILE`	enable/disable use of `LOAD LOCAL INFILE`
`MYSQLI_INIT_CMD`	command to execute after when connecting to MySQL server
`MYSQLI_READ_DEFAULT_FILE`	Read options from named option file instead of `my.cnf`
`MYSQLI_READ_DEFAULT_GROUP`	Read options from the named group from `my.cnf` or the file specified with `MYSQL_READ_DEFAULT_FILE`.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

mysqli_init() e mysqli_real_connect().

Esempi

See mysqli_real_connect().

mysqli_param_count

(PHP 5)

mysqli_param_count -- Alias for mysqli_stmt_param_count()

Description

This function is an alias of mysqli_stmt_param_count(). For a detailled descripton see description of mysqli_stmt_param_count().

Nota: mysqli_param_count() is deprecated and will be removed.

Vedere anche:

mysqli_stmt_param_count().

mysqli_ping

(PHP 5)

mysqli_ping

(no version information, might be only in CVS)

mysqli->ping -- Pings a server connection, or tries to reconnect if the connection has gone down

Description

Procedural style:

bool mysqli_ping ( mysqli link )

Object oriented style (method):

class mysqli {

bool ping ( void )

}

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.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

Our connection is ok!

mysqli_prepare

(PHP 5)

mysqli_prepare

(no version information, might be only in CVS)

mysqli->prepare -- Prepare a SQL statement for execution

Description

Procedure style:

mysqli_stmt mysqli_prepare ( mysqli link, string query )

Object oriented style (method)

class mysqli {

mysqli_stmt prepare ( string query )

}

mysqli_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.

Nota: 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.

Nota: 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 Languange (DML) statements, and not in Data Defination Language (DDL) statements.

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.

Valori restituiti

mysqli_prepare() returns a statement object or FALSE if an error occured.

Vedere anche:

mysqli_stmt_execute(), mysqli_stmt_fetch(), mysqli_stmt_bind_param(), mysqli_stmt_bind_result() e mysqli_stmt_close().

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

Amersfoort is in district Utrecht

mysqli_query

(PHP 5)

mysqli_query

(no version information, might be only in CVS)

mysqli->query -- Performs a query on the database

Description

Procedural style:

mixed mysqli_query ( mysqli link, string query [, int resultmode] )

Object oriented style (method):

class mysqli {

mixed query ( string query [, int resultmode] )

}

The mysqli_query() function is used to simplify the act of performing a query against the database represented by the link parameter.

Functionally, using this function is identical to calling mysqli_real_query() followed either by mysqli_use_result() or mysqli_store_result() where query is the query string itself and resultmode is either the constant MYSQLI_USE_RESULT or MYSQLI_STORE_RESULT depending on the desired behavior. By default, if the resultmode is not provided MYSQLI_STORE_RESULT is used.

If you execute mysqli_query() with resultmode MYSQLI_USE_RESULT all subsequent calls will return error Commands out of sync unless you call mysqli_free_result().

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento. For SELECT, SHOW, DESCRIBE or EXPLAIN mysqli_query() will return a result object.

Vedere anche:

mysqli_real_query(), mysqli_multi_query() e mysqli_free_result().

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

Table myCity successfully created.
Select returned 10 rows.
Error: Commands out of sync;  You can't run this command now

mysqli_real_connect

(PHP 5)

mysqli_real_connect

(no version information, might be only in CVS)

mysqli->real_connect -- Opens a connection to a mysql server

Description

Procedural style

bool mysqli_real_connect ( mysqli link [, string hostname [, string username [, string passwd [, string dbname [, int port [, string socket [, int flags]]]]]]] )

Object oriented style (method)

class mysqli {

bool real_connect ( [string hostname [, string username [, string passwd [, string dbname [, int port [, string socket [, int flags]]]]]]] )

}

mysqli_real_connect() attempts to establish a connection to a MySQL database engine running on hostname.

This function differs from mysqli_connect():

mysqli_real_connect() needs a valid object which has to be created by function mysqli_init()
With function mysqli_options() you can set various options for connection.

With the parameter flags you can set different connection options:

Tabella 1. Supported flags

Name	Description
`MYSQLI_CLIENT_COMPRESS`	Use compression protocol
`MYSQLI_CLIENT_FOUND_ROWS`	return number of matched rows, not the number of affected rows
`MYSQLI_CLIENT_IGNORE_SPACE`	Allow spaces after function names. Makes all function names reserved words.
`MYSQLI_CLIENT_INTERACTIVE`	Allow `interactive_timeout` seconds (instead of `wait_timeout` seconds) of inactivity before closing the connection
`MYSQLI_CLIENT_SSL`	Use SSL (encryption)

Nota: For security reasons the MULTI_STATEMENT flag is not supported in PHP. If you want to execute multiple queries use the mysqli_multi_query() function.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

mysqli_connect(), mysqli_init(), mysqli_options(), mysqli_ssl_set() e mysqli_close().

Esempi

Esempio 1. Object oriented style

<?php

/* create a connection object which is not connected */
$mysqli = mysqli_init();

/* set connection options */
$mysqli->options(MYSQLI_INIT_COMMAND, "SET AUTOCOMMIT=0");
$mysqli->options(MYSQLI_OPT_CONNECT_TIMEOUT, 5);

/* connect to server */
$mysqli->real_connect('localhost', 'my_user', 'my_password', 'world');

/* check connection */
if (mysqli_connect_errno()) {
    printf("Connect failed: %s\n", mysqli_connect_error());
    exit();
}

printf ("Connection: %s\n.", $mysqli->host_info);

$mysqli->close();
?>

Esempio 2. Procedural style

<?php

/* create a connection object which is not connected */
$link = mysqli_init();

/* set connection options */
mysqli_options($link, MYSQLI_INIT_COMMAND, "SET AUTOCOMMIT=0");
mysqli_options($link, MYSQLI_OPT_CONNECT_TIMEOUT, 5);

/* connect to server */
mysqli_real_connect($link, 'localhost', 'my_user', 'my_password', 'world');

/* check connection */
if (mysqli_connect_errno()) {
    printf("Connect failed: %s\n", mysqli_connect_error());
    exit();
}

printf ("Connection: %s\n.", mysqli_get_host_info($link));

mysqli_close($link);
?>

Il precedente esempio visualizzerà:

Connection: Localhost via UNIX socket

mysqli_real_escape_string

(PHP 5)

mysqli_real_escape_string

(no version information, might be only in CVS)

mysqli->real_escape_string -- Escapes special characters in a string for use in a SQL statement, taking into account the current charset of the connection

Description

Procedural style:

string mysqli_real_escape_string ( mysqli link, string escapestr )

Object oriented style (method):

class mysqli {

string real_escape_string ( string escapestr )

}

Characters encoded are NUL (ASCII 0), \n, \r, \, ', ", and Control-Z.

Valori restituiti

Returns an escaped string.

Vedere anche:

mysqli_character_set_name().

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

Error: 42000
1 Row inserted.

mysqli_real_query

(PHP 5)

mysqli_real_query

(no version information, might be only in CVS)

mysqli->real_query -- Execute an SQL query

Description

Procedural style

bool mysqli_real_query ( mysqli link, string query )

Object oriented style (method):

class mysqli {

bool real_query ( string query )

}

The mysqli_real_query() function is used to execute only a query against the database represented by the link whose result can then be retrieved or stored using the mysqli_store_result() or mysqli_use_result() functions.

Nota: In order to determine if a given query should return a result set or not, see mysqli_field_count().

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

mysqli_query(), mysqli_store_result() e mysqli_use_result().

mysqli_report

(PHP 5)

mysqli_report -- Enables or disables internal report functions

Description

bool mysqli_report ( int 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).

Tabella 1. Supported flags

Name	Description
`MYSQLI_REPORT_OFF`	Turns reporting off
`MYSQLI_REPORT_ERROR`	Report errors from mysqli function calls
`MYSQLI_REPORT_INDEX`	Report if no index or bad index was used in a query
`MYSQLI_REPORT_ALL`	Set all options (report all)

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

mysqli_debug() e mysqli_dump_debug_info().

Esempi

Esempio 1. Object oriented style
<?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 warning */ $result = $mysqli->query("SELECT Name FROM City WHERE population > 50000"); $result->close(); $mysqli->close(); ?>

mysqli_rollback

(PHP 5)

mysqli_rollback

(no version information, might be only in CVS)

mysqli->rollback -- Rolls back current transaction

Description

bool mysqli_rollback ( mysqli link )

class mysqli {

bool rollback ( void )

}

Rollbacks the current transaction for the database specified by the link parameter.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

mysqli_commit() e mysqli_autocommit().

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

0 rows in table myCity.
50 rows in table myCity (after rollback).

mysqli_rpl_parse_enabled

(PHP 5)

mysqli_rpl_parse_enabled -- Check if RPL parse is enabled

Description

int mysqli_rpl_parse_enabled ( mysqli link )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

mysqli_rpl_probe

(PHP 5)

mysqli_rpl_probe -- RPL probe

Description

bool mysqli_rpl_probe ( mysqli link )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

mysqli_rpl_query_type

(PHP 5)

mysqli_rpl_query_type

(no version information, might be only in CVS)

mysqli->rpl_query_type -- Returns RPL query type

Description

Procedural style:

int mysqli_rpl_query_type ( mysqli link, string query )

Object oriented style (method)

class mysqli {

int rpl_query_type ( string query )

}

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.

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

mysqli_select_db

(PHP 5)

mysqli_select_db

(no version information, might be only in CVS)

mysqli->select_db -- Selects the default database for database queries

Description

bool mysqli_select_db ( mysqli link, string dbname )

The mysqli_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.

Nota: 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().

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

mysqli_connect() e mysqli_real_connect().

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

Default database is test.
Default database is world.

mysqli_send_long_data

(PHP 5)

mysqli_send_long_data -- Alias for mysqli_stmt_send_long_data()

Description

This function is an alias of mysqli_stmt_send_long_data(). For a detailled descripton see description of mysqli_stmt_send_long_data().

Nota: mysqli_send_long_data() is deprecated and will be removed.

Vedere anche:

mysqli_stmt_send_long_data().

mysqli_send_query

(PHP 5)

mysqli_send_query

(no version information, might be only in CVS)

mysqli->send_query -- Send the query and return

Description

Procedural style:

bool mysqli_send_query ( mysqli link, string query )

Object oriented style (method)

mysqli->set_charset -- Sets the default client character set

Description

bool mysqli_set_charset ( mysqli link, string charset )

The mysqli_set_charset() function sets the default character set (specified by the charset parameter) to be used when sending data from and to the database server represented by the link parameter.

Nota: 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)

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

mysqli_character_set_name() e mysqli_real_escape_string().

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

Current character set: utf8

mysqli_set_opt

(PHP 5)

mysqli_set_opt -- Alias of mysqli_options()

Description

This function is an alias of mysqli_options().

mysqli_sqlstate

(PHP 5)

mysqli_sqlstate

(no version information, might be only in CVS)

mysqli->sqlstate -- Returns the SQLSTATE error from previous MySQL operation

Description

Procedural style:

string mysqli_sqlstate ( mysqli link )

Object oriented style (property):

class mysqli {

string sqlstate

}

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.

Nota: Note that not all MySQL errors are yet mapped to SQLSTATE's. The value HY000 (general error) is used for unmapped errors.

Valori restituiti

Returns a string containing the SQLSTATE error code for the last error. The error code consists of five characters. '00000' means no error.

Vedere anche:

mysqli_errno() e mysqli_error().

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

Error - SQLSTATE 42S01.

mysqli_ssl_set

(PHP 5)

mysqli_ssl_set

(no version information, might be only in CVS)

mysqli->ssl_set -- Used for establishing secure connections using SSL

Description

Procedural style:

bool mysqli_ssl_set ( mysqli link, string key, string cert, string ca, string capath, string cipher )

Object oriented style (method):

class mysqli {

bool ssl_set ( string key, string cert, string ca, string capath, string cipher )

}

The function mysqli_ssl_set() is used for establishing secure connections using SSL. It must be called before mysqli_real_connect(). This function does nothing unless OpenSSL support is enabled.

key is the pathname to the key file. cert is the pathname to the certificate file. ca is the pathname to the certificate authority file. capath is the pathname to a directory that contains trusted SSL CA certificates in pem format. cipher is a list of allowable ciphers to use for SSL encryption. Any unused SSL parameters may be given as NULL

Valori restituiti

This function always returns TRUE value. If SSL setup is incorrect mysqli_real_connect() will return an error when you attempt to connect.

Vedere anche:

mysqli_options() e mysqli_real_connect().

mysqli_stat

(PHP 5)

mysqli_stat

(no version information, might be only in CVS)

mysqli->stat -- Gets the current system status

Description

Procedural style:

string mysqli_stat ( mysqli link )

Object oriented style (method):

class mysqli {

string stat ( void )

}

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.

Valori restituiti

A string describing the server status. FALSE if an error occurred.

Vedere anche:

mysqli_get_server_info().

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

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_affected_rows

(PHP 5)

mysqli_stmt_affected_rows

(no version information, might be only in CVS)

mysqli_stmt->affected_rows -- Returns the total number of rows changed, deleted, or inserted by the last executed statement

Description

Procedural style :

int mysqli_stmt_affected_rows ( mysqli_stmt stmt )

Object oriented style (property):

class mysqli_stmt {

int affected_rows

}

mysqli_stmt_affected_rows() returns the number of rows affected by INSERT, UPDATE, or DELETE query. If the last query was invalid, this function will return -1.

The mysqli_stmt_affected_rows() function only works with queries which update a table. In order to return the number of rows from a SELECT query, use the mysqli_stmt_num_rows() function instead.

Valori restituiti

Nota: 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.

Vedere anche:

mysqli_stmt_num_rows() e mysqli_prepare().

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

rows inserted: 17

mysqli_stmt_bind_param

(PHP 5)

mysqli_stmt_bind_param

(no version information, might be only in CVS)

stmt->bind_param -- Binds variables to a prepared statement as parameters

Description

Procedural style:

bool mysqli_stmt_bind_param ( mysqli_stmt stmt, string types, mixed &var1 [, mixed &...] )

Object oriented style (method):

class mysqli_stmt {

bool bind_param ( string types, mixed &var1 [, mixed &...] )

}

mysqli_stmt_bind_param() is used to bind variables for the parameter markers in the SQL statement that was passed to mysqli_prepare(). The string types contains one or more characters which specify the types for the corresponding bind variables

Tabella 1. 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 send in packages

Nota: If data size of a variable exceeds max. allowed package size (max_allowed_package), you have to specify b in types and use mysqli_stmt_send_long_data() to send the data in packages.
The number of variables and length of string types must match the parameters in the statement.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

mysqli_stmt_bind_result(), mysqli_stmt_execute(), mysqli_stmt_fetch(), mysqli_prepare(), mysqli_stmt_send_long_data(), mysqli_stmt_errno() e mysqli_stmt_error().

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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 */
mysqi_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);
?>

Il precedente esempio visualizzerà:

1 Row inserted.
1 Row deleted.

mysqli_stmt_bind_result

(PHP 5)

mysqli_stmt_bind_result

(no version information, might be only in CVS)

stmt->bind_result -- Binds variables to a prepared statement for result storage

Description

Procedural style:

bool mysqli_stmt_bind_result ( mysqli_stmt stmt, mixed &var1 [, mixed &...] )

Object oriented style (method):

class mysqli_stmt {

bool bind_result ( mixed &var1 [, mixed &...] )

}

mysqli_stmt_bind_result() is used to associate (bind) 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, ....

Nota: Note that all columns must be bound 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.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

mysqli_stmt_bind_param(), mysqli_stmt_execute(), mysqli_stmt_fetch(), mysqli_prepare(), mysqli_stmt_prepare(), mysqli_stmt_init(), mysqli_stmt_errno() e mysqli_stmt_error().

Esempi

Esempio 1. Object oriented style

<?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();

?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

AFG Afghanistan
ALB Albania
DZA Algeria
ASM American Samoa
AND Andorra

mysqli_stmt_close

(PHP 5)

mysqli_stmt_close

(no version information, might be only in CVS)

mysqli_stmt->close -- Closes a prepared statement

Description

Procedural style:

bool mysqli_stmt_close ( mysqli_stmt stmt )

Object oriented style (method):

class mysqli_stmt {

bool close ( void )

}

Closes a prepared statement. mysqli_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.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

mysqli_stmt_data_seek

(PHP 5)

mysqli_stmt_data_seek

(no version information, might be only in CVS)

stmt->data_seek -- Seeks to an arbitray row in statement result set

Description

Procedural style:

void mysqli_stmt_data_seek ( mysqli_stmt statement, int offset )

Object oriented style (method):

class mysqli_stmt {

void data_seek ( int offset )

}

The mysqli_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..mysqli_stmt_num_rows() - 1).

Valori restituiti

Returns NULL on success or FALSE on failure.

Vedere anche:

mysqli_stmt_error() e mysqli_stmt_sqlstate().

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

City: Benin City  Countrycode: NGA

mysqli_stmt_errno

(PHP 5)

mysqli_stmt_errno

(no version information, might be only in CVS)

mysqli_stmt->errno -- Returns the error code for the most recent statement call

Description

Procedural style :

int mysqli_stmt_errno ( mysqli_stmt stmt )

Object oriented style (property):

class mysqli_stmt {

int errno

}

For the statement specified by stmt, mysqli_stmt_errno() returns the error code for the most recently invoked statement function that can succeed or fail.

Nota: 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.

Valori restituiti

An error code value. Zero means no error occurred.

Vedere anche:

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

Error: 1146.

mysqli_stmt_error

(PHP 5)

mysqli_stmt_error

(no version information, might be only in CVS)

mysqli_stmt->error -- Returns a string description for last statement error

Description

Procedural style:

string mysqli_stmt_error ( mysqli_stmt stmt )

Object oriented style (property):

class mysqli_stmt {

string error

}

For the statement specified by stmt, mysqli_stmt_error() returns a containing the error message for the most recently invoked statement function that can succeed or fail.

Valori restituiti

A string that describes the error. An empty string if no error occurred.

Vedere anche:

mysqli_stmt_errno() e mysqli_stmt_sqlstate().

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

Error: Table 'world.myCountry' doesn't exist.

mysqli_stmt_execute

(PHP 5)

mysqli_stmt_execute

(no version information, might be only in CVS)

stmt->execute -- Executes a prepared Query

Description

Procedural style:

bool mysqli_stmt_execute ( mysqli_stmt stmt )

Object oriented style (method):

class mysqli_stmt {

bool execute ( void )

}

The mysqli_stmt_execute() function executes a query that has been previously prepared using the mysqli_prepare() function represented by the stmt object. 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 mysqli_stmt_affected_rows() function. Likewise, if the query yields a result set the mysqli_stmt_fetch() function is used.

Nota: When using mysqli_stmt_execute(), the mysqli_stmt_fetch() function must be used to fetch the data prior to performing any additional queries.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

mysqli_prepare() e mysqli_stmt_bind_param().

Esempi

Esempio 1. Object oriented style

<?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(); 
?>

Esempio 2. Procedural style

<?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); 
?>

Il precedente esempio visualizzerà:

Stuttgart (DEU,Baden-Wuerttemberg)
Bordeaux (FRA,Aquitaine)

mysqli_stmt_fetch

(PHP 5)

mysqli_stmt_fetch

(no version information, might be only in CVS)

stmt->fetch -- Fetch results from a prepared statement into the bound variables

Description

Procedural style:

bool mysqli_stmt_fetch ( mysqli_stmt stmt )

Object oriented style (method):

class mysqli_stmt {

bool fetch ( void )

}

mysqli_stmt_fetch() fetch the result from a prepared statement into the variables bound by mysqli_stmt_bind_result().

Nota: Note that all columns must be bound by the application before calling mysqli_stmt_fetch().

Valori restituiti

Tabella 1. Valori restituiti

Value	Description
`TRUE`	Success. Data has been fetched
`FALSE`	Error occured
`NULL`	No more rows/data exists or data truncation occurred

Vedere anche:

mysqli_prepare(), mysqli_stmt_errno(), mysqli_stmt_error() e mysqli_stmt_bind_result().

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

Rockford (USA)
Tallahassee (USA)
Salinas (USA)
Santa Clarita (USA)
Springfield (USA)

mysqli_stmt_free_result

(PHP 5)

mysqli_stmt_free_result

(no version information, might be only in CVS)

stmt->free_result -- Frees stored result memory for the given statement handle

Description

Procedural style:

void mysqli_stmt_free_result ( mysqli_stmt stmt )

Object oriented style (method):

class mysqli_stmt {

void free_result ( void )

}

The mysqli_stmt_free_result() function frees the result memory associated with the statement represented by the stmt parameter, which was allocated by mysqli_stmt_store_result().

Valori restituiti

This function doesn't return any value.

Vedere anche:

mysqli_stmt_store_result().

mysqli_stmt_init

(PHP 5)

mysqli_stmt_init

(no version information, might be only in CVS)

mysqli->stmt_init -- Initializes a statement and returns an object for use with mysqli_stmt_prepare

Description

Procedural style :

mysqli_stmt mysqli_stmt_init ( mysqli link )

Object oriented style (property):

class mysqli {

mysqli_stmt stmt_init ( void )

}

Allocates and initializes a statement object suitable for mysqli_stmt_prepare().

Nota: Any subsequent calls to any mysqli_stmt function will fail until mysqli_stmt_prepare() was called.

Valori restituiti

Returns an object.

Vedere anche:

mysqli_stmt_prepare().

mysqli_stmt_num_rows

(PHP 5)

mysqli_stmt_num_rows

(no version information, might be only in CVS)

stmt->num_rows -- Return the number of rows in statements result set

Description

Procedural style :

int mysqli_stmt_num_rows ( mysqli_stmt stmt )

Object oriented style (property):

class mysqli_stmt {

int num_rows

}

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.

Valori restituiti

An integer representing the number of rows in result set.

Vedere anche:

mysqli_stmt_affected_rows(), mysqli_prepare() e mysqli_stmt_store_result().

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

Number of rows: 20.

mysqli_stmt_param_count

(PHP 5)

mysqli_stmt_param_count

(no version information, might be only in CVS)

stmt->param_count -- Returns the number of parameter for the given statement

Description

Procedural style:

int mysqli_stmt_param_count ( mysqli_stmt stmt )

Object oriented style (property):

class mysqli_stmt {

int param_count

}

mysqli_stmt_param_count() returns the number of parameter markers present in the prepared statement.

Valori restituiti

returns an integer representing the number of parameters.

Vedere anche:

mysqli_stmt_init(), mysqli_stmt_execute(), mysqli_stmt_fetch(), mysqli_stmt_bind_param(), mysqli_stmt_bind_result() e mysqli_stmt_close().

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

Statement has 2 markers.

mysqli_stmt_prepare

(PHP 5)

mysqli_stmt_prepare

(no version information, might be only in CVS)

stmt->prepare -- Prepare a SQL statement for execution

Description

Procedure style:

bool mysqli_stmt_prepare ( mysqli_stmt stmt, string query )

Object oriented style (method)

class mysqli_stmt {

mixed prepare ( string query )

}

mysqli_stmt_prepare() prepares the SQL query pointed to by the null-terminated string query. The statement object has to be allocated by mysqli_stmt_init(). The query must consist of a single SQL statement.

Nota: 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.

Nota: 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 mysqli_stmt_bind_param() and/or mysqli_stmt_bind_result() before executing the statement or fetching rows.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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();
if ($stmt = 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);
?>

Il precedente esempio visualizzerà:

Amersfoort is in district Utrecht

mysqli_stmt_reset

(PHP 5)

mysqli_stmt_reset

(no version information, might be only in CVS)

stmt->reset -- Resets a prepared statement

Description

Procedural style:

bool mysqli_stmt_reset ( mysqli_stmt stmt )

Object oriented style (method):

class mysqli_stmt {

bool reset ( void )

}

The mysqli_stmt_reset() resets a prepared statement on client and server to state after prepare. For now this is mainly used to reset data sent with mysqli_stmt_send_long_data().

Nota: To prepare a statement with another query use function mysqli_stmt_prepare().

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

mysqli_prepare() e mysqli_free_result().

mysqli_stmt_result_metadata

(PHP 5)

mysqli_stmt_result_metadata -- Returns result set metadata from a prepared statement

Description

Procedural style:

mysqli_result mysqli_stmt_result_metadata ( mysqli_stmt stmt )

Object oriented style (method):

class mysqli_stmt {

mysqli_result result_metadata ( void )

}

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.

Nota: This result set pointer can be passed as an argument to any of the field-based functions that process result set metadata, such as:
mysqli_num_fields()
mysqli_fetch_field()
mysqli_fetch_field_direct()
mysqli_fetch_fields()
mysqli_field_count()
mysqli_field_seek()
mysqli_field_tell()
mysqli_free_result()

The result set structure should be freed when you are done with it, which you can do by passing it to mysqli_free_result()

Nota: 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().

Valori restituiti

mysqli_stmt_result_metadata() returns a result object or FALSE if an error occured.

Vedere anche:

Esempi

Esempio 1. Object oriented style
<?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(); ?>

Esempio 2. Procedural style
<?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); ?>

mysqli_stmt_send_long_data

(PHP 5)

mysqli_stmt_send_long_data

(no version information, might be only in CVS)

stmt->send_long_data -- Send data in blocks

Description

Procedural style:

bool mysqli_stmt_send_long_data ( mysqli_stmt stmt, int param_nr, string data )

Object oriented style (method)

class mysqli_stmt {

bool send_long_data ( int param_nr, string data )

}

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.

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.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

mysqli_prepare() e mysqli_stmt_bind_param().

mysqli_stmt_sqlstate

(PHP 5)

mysqli_stmt_sqlstate -- Returns SQLSTATE error from previous statement operation

Description

string mysqli_stmt_sqlstate ( mysqli_stmt stmt )

Nota: Note that not all MySQL errors are yet mapped to SQLSTATE's. The value HY000 (general error) is used for unmapped errors.

Valori restituiti

Returns a string containing the SQLSTATE error code for the last error. The error code consists of five characters. '00000' means no error.

Vedere anche:

mysqli_stmt_errno() e mysqli_stmt_error().

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

Error: 42S02.

mysqli_stmt_store_result

(PHP 5)

mysqli_stmt_store_result

(no version information, might be only in CVS)

mysqli_stmt->store_result -- Transfers a result set from a prepared statement

Description

Procedural style:

bool mysqli_stmt_store_result ( mysqli_stmt stmt )

Object oriented style (method):

class mysqli_stmt {

bool store_result ( void )

}

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.

Nota: 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.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

mysqli_prepare(), mysqli_stmt_result_metadata() e mysqli_stmt_fetch().

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

Number of rows: 20.

mysqli_store_result

(PHP 5)

mysqli_store_result

(no version information, might be only in CVS)

mysqli->store_result -- Transfers a result set from the last query

Description

Procedural style:

mysqli_result mysqli_store_result ( mysqli link )

Object oriented style (method):

class mysqli {

mysqli_result store_result ( void )

}

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.

Nota: Although it is always good practice to free the memory used by the result of a query using the mysqli_free_result() function, when transfering large result sets using the mysqli_store_result() this becomes particularly important.

Nota: mysqli_store_result() returns FALSE in case the query didn't return a result set (if the query was, for example an INSERT statement). This function also returns FALSE if 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 returning FALSE after successfull 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.

Valori restituiti

Returns a buffered result object or FALSE if an error occurred.

Vedere anche:

mysqli_real_query() e mysqli_use_result().

Esempi

See mysqli_multi_query().

mysqli_thread_id

(PHP 5)

mysqli_thread_id

(no version information, might be only in CVS)

mysqli->thread_id -- Returns the thread ID for the current connection

Description

Procedural style:

int mysqli_thread_id ( mysqli link )

Object oriented style (property):

class mysqli {

int thread_id

}

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.

Nota: 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.

Valori restituiti

mysqli_thread_id() returns the Thread ID for the current connection.

Vedere anche:

mysqli_kill().

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

Error: MySQL server has gone away

mysqli_thread_safe

(PHP 5)

mysqli_thread_safe -- Returns whether thread safety is given or not

Description

Procedural style:

bool mysqli_thread_safe ( void )

mysqli_thread_safe() indicates whether the client library is compiled as thread-safe.

Valori restituiti

TRUE if the client library is thread-safe, otherwise FALSE.

mysqli_use_result

(PHP 5)

mysqli_use_result

(no version information, might be only in CVS)

mysqli->use_result -- Initiate a result set retrieval

Description

Procedural style:

mysqli_result mysqli_use_result ( mysqli link )

Object oriented style (method):

class mysqli {

mysqli_result use_result ( void )

}

mysqli_use_result() is used to initiate the retrieval of a result set from the last query executed using the mysqli_real_query() function on the database connection specified by the link parameter. 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.

Nota: 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.

Valori restituiti

Returns an unbuffered result object or FALSE if an error occurred.

Vedere anche:

mysqli_real_query() e mysqli_store_result().

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

my_user@localhost
-----------------
Amersfoort
Maastricht
Dordrecht
Leiden
Haarlemmermeer

mysqli_warning_count

(PHP 5)

mysqli_warning_count

(no version information, might be only in CVS)

mysqli->warning_count -- Returns the number of warnings from the last query for the given link

Description

Procedural style:

int mysqli_warning_count ( mysqli link )

Object oriented style (property):

class mysqli {

int warning_count

}

mysqli_warning_count() returns the number of warnings from the last query in the connection represented by the link parameter.

Nota: For retrieving warning messages you can use the SQL command SHOW WARNINGS [limit row_count].

Valori restituiti

Number of warnings or zero if there are no warnings.

Vedere anche:

mysqli_errno(), mysqli_error() e mysqli_sqlstate().

Esempi

Esempio 1. Object oriented style

<?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();
?>

Esempio 2. Procedural style

<?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);
?>

Il precedente esempio visualizzerà:

Warning (1264): Data truncated for column 'Name' at row 1

LXXXIX. Ncurses Terminal Screen Control Functions

Introduzione

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.

Avvertimento

Ncurses is available for the following platforms:

AIX
BeOS
Cygwin
Digital Unix (aka OSF1)
FreeBSD
GNU/Linux
HPUX
IRIX
OS/2
SCO OpenServer
Solaris
SunOS

Requisiti

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.

Installazione

To get these functions to work, you have to compile the CGI or CLI version of PHP with --with-ncurses[=DIR].

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

Tabella 1. Ncurses configuration options

Name	Default	Changeable	Changelog
ncurses.value	"42"	PHP_INI_ALL
ncurses.string	"foobar"	PHP_INI_ALL

Per maggiori dettagli sulle costanti PHP_INI_* vedere Appendice G.

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

Error codes

On error ncurses functions return NCURSES_ERR.

Colors

Tabella 2. ncurses color constants

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

Tabella 3. ncurses key constants

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	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

Tabella 4. mouse constants

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

Sommario
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 -- Check if we can change terminals colors
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 -- Gets the RGB value for color
ncurses_color_set -- Set fore- and background color
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 -- Check if terminal has colors
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 -- Set new RGB value for color
ncurses_init_pair -- Allocate 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 -- Gets the RGB value for color
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 -- Start using colors
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

ncurses_cbreak() disables line buffering and character processing (interrupt and flow control characters are unaffected), making characters typed by the user immediately available to the program.

ncurses_cbreak() returns TRUE or NCURSES_ERR if any error occurred.

ncurses_clear

(PHP 4 >= 4.1.0, PHP 5)

ncurses_clear -- Clear screen

Description

bool ncurses_getmouse ( array &mevent )

Avvertimento

ncurses_getmouse() reads mouse event out of queue. Function ncurses_getmouse() will return ;FALSE if a mouse event is actually visible in the given window, otherwise it will return TRUE. Event options will be delivered in parameter mevent, 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

Avvertimento

Function ncurses_mousemask() will set mouse events to be reported. By default no mouse events will be reported. The function ncurses_mousemask() will return a mask to indicated which of the in parameter newmask specified mouse events can be reported. On complete failure, it returns 0. In parameter oldmask, which is passed by reference ncurses_mousemask() returns the previous value of mouse event mask. 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().

As a side effect, setting a zero mousemask in newmask turns off the mouse pointer. Setting a non zero value turns mouse pointer on.

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

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

If panel is null, returns the bottom panel in the stack.

ncurses_panel_below

(PHP 4 >= 4.3.0, PHP 5)

ncurses_panel_below -- Returns the panel below panel

Description

bool ncurses_ungetmouse ( array mevent )

Avvertimento

ncurses_getmouse() 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. Event options will be specified in associative array mevent:

"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

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

XC. Funzioni di rete

Introduzione

Requisiti

Non sono necessarie librerie esterne per utilizzare questo modulo.

Installazione

Non è necessaria nessuna installazione per usare queste funzioni, esse fanno parte del core di PHP.

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

Tabella 1. Parametri di configurazione.

Nome	Default	Modificabile
define_syslog_variables	"0"	PHP_INI_ALL

Per maggiori dettagli e definizioni delle costanti PHP_INI_* vedere ini_set().

Breve descrizione dei parametri di configurazione.

define_syslog_variables boolean: Inposta se definire o meno le varie varaibili di syslog (quali $LOG_PID, $LOG_CRON, etc.). Disattivarle ha effetti positivi sulle performance. A runtime, queste variabili possono essere definit richiamando define_syslog_variables().

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

Le costanti qui elencate sono sempre disponibili in quanto parte del core di PHP.

Tabella 2. Opzioni openlog()

Costante	Descrizione
LOG_CONS	Se si verifica un errore nella scrittura nel log di sistema scrive direttamente sulla console.
LOG_NDELAY	Apre immediatamente la connessione con il log
LOG_ODELAY	(default) attende ad aprire la connessione fino a quando non vi è un messaggio da registrare.
LOG_NOWAIT
LOG_PERROR	Scrive il messaggio di log anche nello standard error
LOG_PID	Include anche il PID in ciascun messaggio

Tabella 3. Tools openlog()

Costante	Descrizione
LOG_AUTH	Messaggio di sicurezza/autorizzazione (utilizzare LOG_AUTHPRIV nei sistemi in cui questa costante è definita)
LOG_AUTHPRIV	Messaggi di sicurezza/autorizzazione (privati)
LOG_CRON	Demone dell'ora (cron ed at)
LOG_DAEMON	Altri demoni di sistema
LOG_KERN	Messaggi del kernel
LOG_LOCAL0 ... LOG_LOCAL7	Riservato per utilizzi locali, questi non sono dipsonibili in Windows
LOG_LPR	Sottosistema della stampante
LOG_MAIL	Sottosistema di posta
LOG_NEWS	Sottosistema USENET news
LOG_SYSLOG	Messaggi generati internamente da syslogd
LOG_USER	Messaggi utente generici
LOG_UUCP	Sottosistema UUCP

Tabella 4. Priorità (in ordine decrescente) di syslog()

Costante	Descrizione
LOG_EMERG	Sistema inutilizzabile
LOG_ALERT	Azioni devono essere intraprese immediatamente
LOG_CRIT	Condizioni critiche
LOG_ERR	Condizioni di errore
LOG_WARNING	Condizioni di attenzione
LOG_NOTICE	Situazione normale, ma significativa
LOG_INFO	Messaggio informativo
LOG_DEBUG	Messaggio di debug

Tabella 5. Parametri dns_get_record()

Costante	Descrizione
DNS_A	Risorsa con indirizzo IPv4
DNS_MX	Mail Exchanger Resource
DNS_CNAME	Alias (Canonical Name) Resource
DNS_NS	Authoritative Name Server Resource
DNS_PTR	Pointer Resource
DNS_HINFO	Host Info Resource (Vedere la pagina IANA Operating System Names per il significato di questi valori)
DNS_SOA	Start of Authority Resource
DNS_TXT	Text Resource
DNS_ANY	Any Resource Record. In molti sistemi questo restituisce tutti i record, tuttavia non si dovrebbe farne affidamento per utilzzi critici. Piuttosto utilizzare DNS_ALL.
DNS_AAAA	IPv6 Address Resource
DNS_ALL	Interroga in modo iterativo il DNS alla ricerca di ogni tipo di record disponibile.

Sommario
checkdnsrr -- Controlla i record DNS relativi ad un host Internet o indirizzo IP
closelog -- Chiude la connessione al logger di sistema
debugger_off -- Disattiva il debugger interno PHP
debugger_on -- Attiva il debugger interno PHP
define_syslog_variables -- Inizializza tutte le costanti collegate al syslog
dns_check_record -- Synonym for checkdnsrr()
dns_get_mx -- Synonym for getmxrr()
dns_get_record -- Fetch DNS Resource Records associated with a hostname
fsockopen -- Apre una connessione a un socket appartenente a un dominio Internet o Unix
gethostbyaddr -- Ottiene l'host Internet corrispondente a un dato indirizzo IP
gethostbyname -- Ottiene l'indirizzo IP corrispondente a un dato hostname Internet
gethostbynamel -- Ottiene la lista degli indirizzi IP corrispondenti a un dato hostname Internet
getmxrr -- Ottiene i record MX corrispondenti a un dato nome di host Internet
getprotobyname -- Ottiene il numero del protocollo associato al nome del protocollo
getprotobynumber -- Ottiene il nome del protocollo associato al numero del protocollo
getservbyname -- Ottiene il numero di porta associato ad un servizio Internet e ad un protocollo
getservbyport -- Ottiene il servizio Internet corrispondente ad una porta e ad un protocollo
inet_ntop -- Converts a packed internet address to a human readable representation
inet_pton -- Converts a human readable IP address to its packed in_addr representation
ip2long -- Converts a string containing an (IPv4) Internet Protocol dotted address into a proper address. Converte una stringa contenente un indirizzo di rete del Protocollo Internet (IPv4) in un indirizzo espresso come tipo di dato int.
long2ip -- Converte un indirizzo di rete del Protocollo Internet (IPv4) in una stringa contenente un indirizzo espresso secondo la notazione standard di Internet.
openlog -- Apre una connessione al logger di sistema
pfsockopen -- Apre una connessione persistente Internet o di tipo domain socket Unix
socket_get_status -- Alias di stream_get_meta_data()
socket_set_blocking -- Alias di stream_set_blocking()
socket_set_timeout -- Alias di stream_set_timeout()
syslog -- Genera un messaggio del system log

checkdnsrr

(PHP 3, PHP 4, PHP 5)

checkdnsrr -- Controlla i record DNS relativi ad un host Internet o indirizzo IP

Descrizione

int checkdnsrr ( string host [, string type] )

Cerca i record DNS del tipo type corrispondenti a host. Restituisce vero se dei records sono trovati; falso se nessun record viene trovato o in caso di errore.

type può essere uno dei seguenti: A, MX, NS, SOA, PTR, CNAME, oppure ANY. Il default è MX.

Host può essere sia l'indirizzo IP in notazione decimale o il nome dell'host.

Nota: Questa funzione non è implementata su piattaforme Windows

Vedere anche getmxrr(), gethostbyaddr(), gethostbyname(), gethostbynamel() e la man page named(8).

closelog

(PHP 3, PHP 4, PHP 5)

closelog -- Chiude la connessione al logger di sistema

Descrizione

int closelog ( void )

void define_syslog_variables ( void )

array dns_get_record ( string hostname [, int type [, array &authns, array &addtl]] )

Nota: This function is not implemented on Windows platforms, nor does it (currently) work on *BSD systems. Try the PEAR class Net_DNS.

This function returns an array of associative arrays. Each associative array contains at minimum the following keys:

Tabella 1. Basic DNS attributes

Attribute	Meaning
host	The record in the DNS namespace to which the rest of the associated data refers.
class	dns_get_record() only returns Internet class records and as such this parameter will always return `IN`.
type	String containing the record type. Additional attributes will also be contained in the resulting array dependant on the value of type. See table below.
ttl	Time To Live remaining for this record. This will not equal the record's original ttl, but will rather equal the original ttl minus whatever length of time has passed since the authoritative name server was queried.

hostname should be a valid DNS hostname such as "www.example.com". Reverse lookups can be generated using in-addr.arpa notation, but gethostbyaddr() is more suitable for the majority of reverse lookups.

By default, dns_get_record() will search for any resource records associated with hostname. To limit the query, specify the optional type parameter. type may be any one of the following: DNS_A, DNS_CNAME, DNS_HINFO, DNS_MX, DNS_NS, DNS_PTR, DNS_SOA, DNS_TXT, DNS_AAAA, DNS_SRV, DNS_NAPTR, DNS_A6, DNS_ALL or DNS_ANY. The default is DNS_ANY.

Nota: Because of eccentricities in the performance of libresolv between platforms, DNS_ANY will not always return every record, the slower DNS_ALL will collect all records more reliably.

The optional third and fourth arguments to this function, authns and addtl are passed by reference and, if given, will be populated with Resource Records for the Authoritative Name Servers, and any Additional Records respectively. See the example below.

Tabella 2. Other keys in associative arrays dependant on 'type'

Type	Extra Columns
`A`	`ip`: An IPv4 addresses in dotted decimal notation.
`MX`	`pri`: Priority of mail exchanger. Lower numbers indicate greater priority. `target`: FQDN of the mail exchanger. See also dns_get_mx().
`CNAME`	`target`: FQDN of location in DNS namespace to which the record is aliased.
`NS`	`target`: FQDN of the name server which is authoritative for this hostname.
`PTR`	`target`: Location within the DNS namespace to which this record points.
`TXT`	`txt`: Arbitrary string data associated with this record.
`HINFO`	`cpu`: IANA number designating the CPU of the machine referenced by this record. `os`: IANA number designating the Operating System on the machine referenced by this record. See IANA's Operating System Names for the meaning of these values.
`SOA`	`mname`: FQDN of the machine from which the resource records originated. `rname`: Email address of the administrative contain for this domain. `serial`: Serial # of this revision of the requested domain. `refresh`: Refresh interval (seconds) secondary name servers should use when updating remote copies of this domain. `retry`: Length of time (seconds) to wait after a failed refresh before making a second attempt. `expire`: Maximum length of time (seconds) a secondary DNS server should retain remote copies of the zone data without a successful refresh before discarding. `minimum-ttl`: Minimum length of time (seconds) a client can continue to use a DNS resolution before it should request a new resolution from the server. Can be overridden by individual resource records.
`AAAA`	`ipv6`: IPv6 address
`A6`(PHP >= 5.1.0)	`masklen`: Length (in bits) to inherit from the target specified by `chain`. `ipv6`: Address for this specific record to merge with `chain`. `chain`: Parent record to merge with `ipv6` data.
`SRV`	`pri`: (Priority) lowest priorities should be used first. `weight`: Ranking to weight which of commonly prioritized `targets` should be chosen at random. `target` and `port`: hostname and port where the requested service can be found. For additional information see: RFC 2782
`NAPTR`	`order` and `pref`: Equivalent to `pri` and `weight` above. `flags`, `services`, `regex`, and `replacement`: Parameters as defined by RFC 2915.

Nota: Per DNS standards, email addresses are given in user.host format (for example: hostmaster.example.com as opposed to hostmaster@example.com), be sure to check this value and modify if necessary before using it with a functions such as mail().

Esempio 1. Using dns_get_record()

<?php
$result = dns_get_record("php.net");
print_r($result);
?>

Produces output similar to the following:

Array
(
    [0] => Array
        (
            [host] => php.net
            [type] => MX
            [pri] => 5
            [target] => pair2.php.net
            [class] => IN
            [ttl] => 6765
        )

    [1] => Array
        (
            [host] => php.net
            [type] => A
            [ip] => 64.246.30.37
            [class] => IN
            [ttl] => 8125
        )

)

Since it's very common to want the IP address of a mail server once the MX record has been resolved, dns_get_record() also returns an array in addtl which contains associate records. authns is returned as well containing a list of authoritative name servers.

Esempio 2. Using dns_get_record() and DNS_ANY

<?php
/* Request "ANY" record for php.net, 
   and create $authns and $addtl arrays
   containing list of name servers and
   any additional records which go with
   them */
$result = dns_get_record("php.net", DNS_ANY, $authns, $addtl);
echo "Result = ";
print_r($result);
echo "Auth NS = ";
print_r($authns);
echo "Additional = ";
print_r($addtl);
?>

Produces output similar to the following:

fsockopen

(PHP 3, PHP 4, PHP 5)

fsockopen -- Apre una connessione a un socket appartenente a un dominio Internet o Unix

Descrizione

int fsockopen ( string hostname, int porta [, int errno [, string errstr [, float timeout]]] )

Inizializza una connessione nel dominio Internet (AF_INET, usando TCP o UDP) o Unix (AF_UNIX). Per il dominio Internet, apre una connessione a un socket TCP verso l' hostname sulla porta port. hostname può essere in questo caso, sia un fully qualified domain name o un indirizzo IP. Per le connessioni UDP, è necessario specificare esplicitamente il protocollo, usando: 'udp://' come prefisso di hostname. Per il dominio Unix, hostname viene utilizzato come percorso verso il socket, in questo caso, porta deve essere impostato a 0. Il parametro opzionale timeout può essere usato per impostare un timeout in secondi per la chiamata di sistema connect.

A partire da PHP 4.3.0, se si è compilato con il supporto OpenSSL, si può prefissare hostname con 'ssl://' oppure 'tls://' per utilizzare una connessione client SSL o TLS su una connessione TCP/IP per connettersi all'host remoto.

fsockopen() restituisce un puntatore a file che può essere usato nelle altre funzioni orientate ai file (come fgets(), fgetss(), fputs(), fclose() e feof()).

Se la chiamata non ha successo, viene restituito FALSE e se gli argomenti opzionali errno e errstr sono presenti, vengono impostati a indicare l'errore a livello di sistema che è avvenuto nella chiamata alla funzione connect() del sistema operativo. Se il valore di errno restituito è 0 e la funzione restituisce FALSE, è un'indicazione che l'errore è avvenuto prima della chiamata di connect(). Questo è molto probabilmente legato ad un problema di inizializzazione del socket. Si noti che gli argomenti errno e errstr verranno sempre passati by reference.

A seconda dell'ambiente operativo, il dominio Unix o l'opzionale timeout della connect potrebbero non essere disponibili.

Il socket viene aperto di default in modo blocking. Si può passare al modo non-blocking usando socket_set_blocking().
Esempio 1. Esempio di fsockopen()
<?php $fp = fsockopen ("www.php.net", 80, $errno, $errstr, 30); if (!$fp) { echo "$errstr ($errno)<br>\n"; } else { fputs ($fp, "GET / HTTP/1.0\r\nHost: www.php.net\r\n\r\n"); while (!feof($fp)) { echo fgets ($fp,128); } fclose ($fp); } ?>
L'esempio seguente mostra come ottenere data e ora tramite il servizio UDP "daytime" (porta 13) della vostra stessa macchina.
Esempio 2. Uso di connessione UDP
<?php $fp = fsockopen("udp://127.0.0.1", 13, $errno, $errstr); if (!$fp) { echo "ERRORE: $errno - $errstr<br>\n"; } else { fwrite($fp,"\n"); echo fread($fp, 26); fclose($fp); } ?>

Nota: Il parametro timeout è stato introdotto nel PHP 3.0.9 e il supporto UDP è stato aggiunto nel PHP 4.

getservbyname() restituisce la porta Internet corrispondente a servizio per il protocollo specificato come in /etc/services. protocollo può essere sia "tcp" che "udp" (scritti in minuscolo). Restituisce FALSE se service o protocol non sono trovati.

Esempio 1. Esempio di uso di getservbyname()
<?php $services = array('http', 'ftp', 'ssh', 'telnet', 'imap', 'smtp', 'nicname', 'gopher', 'finger', 'pop3', 'www'); foreach ($services as $service) { $port = getservbyname($service, 'tcp'); echo $service . ": " . $port . "<br />\n"; } ?>

Per avere la lista completa dei numeri di porta vedere: http://www.iana.org/assignments/port-numbers.

Vedere anche: getservbyport().

getservbyport

(PHP 4, PHP 5)

getservbyport -- Ottiene il servizio Internet corrispondente ad una porta e ad un protocollo

Descrizione

string getservbyport ( int porta, string protocollo )

getservbyport() restituisce il servizio Internet associato a porta relativamente al protocollo specificato come in /etc/services. protocollo può essere sia "tcp" che "udp" (scritti in minuscolo).

Vedere anche: getservbyname().

inet_ntop

(PHP 5 >= 5.1.0RC1)

inet_ntop -- Converts a packed internet address to a human readable representation

Description

string inet_ntop ( string in_addr )

This function converts a 32bit IPv4, or 128bit IPv6 address (if PHP was built with IPv6 support enabled) into an address family appropriate string representation. Returns FALSE on failure.

Esempio 1. inet_ntop() Example

<?php
$packed = chr(127) . chr(0) . chr(0) . chr(1);
$expanded = inet_ntop($packed);

/* Outputs: 127.0.0.1 */
echo $expanded;

$packed = str_repeat(chr(0), 15) . chr(1);
$expanded = inet_ntop($packed);

/* Outputs: ::1 */
echo $expanded;
?>

Nota: Questa funzione non è implementata su piattaforme Windows

See also long2ip(), inet_pton(), and ip2long().

inet_pton

(PHP 5 >= 5.1.0RC1)

inet_pton -- Converts a human readable IP address to its packed in_addr representation

Description

string inet_pton ( string address )

This function converts a human readable IPv4 or IPv6 address (if PHP was built with IPv6 support enabled) into an address family appropriate 32bit or 128bit binary structure.

Esempio 1. inet_pton() Example

<?php
$in_addr = inet_pton('127.0.0.1');

$in6_addr = inet_pton('::1');

?>

Nota: Questa funzione non è implementata su piattaforme Windows

See also ip2long(), inet_ntop(), and long2ip().

ip2long

(PHP 4, PHP 5)

ip2long -- Converts a string containing an (IPv4) Internet Protocol dotted address into a proper address. Converte una stringa contenente un indirizzo di rete del Protocollo Internet (IPv4) in un indirizzo espresso come tipo di dato int.

Descrizione

int ip2long ( string indirizzo_ip )

La funzione ip2long() genera un indirizzo di rete Internet IPv4 a partire dalla rappresentazione in formato standard (stringa separata da punti).
Esempio 1. Esempio di ip2long()
<?php $ip = gethostbyname("www.php.net"); $out = "I seguenti URL sono equivalenti:<br>\n"; $out .= "http://www.php.net/, http://".$ip."/, e http://".sprintf("%u",ip2long($ip))."/<br>\n"; echo $out; ?>

Nota: Poiché il tipo di dato integer in PHP è signed e molti indirizzi IP risulterebbero essere interi negativi, è necessario usare il formattatore "%u" della funzione sprintf() e printf() per ottenere la rappresentazione in stringa dell'indirizzo IP in modo nsigned.

Questo secondo esempio mostra come stampare un indirizzo convertito, usando la funzione printf():

Esempio 2. Visualizzazione di un indirizzo IP

<?php
$ip = gethostbyname("www.php.net");
printf("%u\n", ip2long($ip));
echo $out;
?>

Vedere anche: long2ip()

long2ip

(PHP 4, PHP 5)

long2ip -- Converte un indirizzo di rete del Protocollo Internet (IPv4) in una stringa contenente un indirizzo espresso secondo la notazione standard di Internet.

Descrizione

string long2ip ( int proper_address )

La funzione long2ip() genera un indirizzo Internet in formato separato da punti (es.: aaa.bbb.ccc.ddd) a partire dalla rappresentazione propria.

Vedere anche: ip2long()

openlog

(PHP 3, PHP 4, PHP 5)

openlog -- Apre una connessione al logger di sistema

Descrizione

int openlog ( string ident, int option, int facility )

openlog() apre una connessione al logger di sistema per un programma. La stringa ident viene aggiunta a ogni messaggio. Valori per option e facility sono dati di seguito. L'argomento option viene usato per indicare quali opzioni di loggin verranno usate durante la generazione di un messaggio di log. L'argomento facility viene usato per specificare quale tipo di programma sta loggando il messaggio. Questo permette di specificare (nella comfigurazione del syslog della macchina) come trattare i messaggi provenienti dalle diverse facility. L'uso di openlog() è opzionale. Viene chiamato automaticamente da syslog() se necessario, in tal caso ident sarà di default FALSE.

Tabella 1. Opzioni di openlog()

Costante	Descrizione
LOG_CONS	se si verifica un errore durante l'invio dei dati al logger di sistema, scrive direttamente sulla console di sistema
LOG_NDELAY	apre immediatamente una connessione al logger
LOG_ODELAY	(default) ritarda l'apertura della connessione fino a quando non viene loggato il primo messaggio
LOG_PERROR	stampa un messaggio di log anche su standard error
LOG_PID	include il PID in ciascun messaggio

Si possono usare una o più di queste opzioni. Usando opzioni multiple è necessario usare OR, ad esempio per aprire la connessione immediatamente, scrivere sulla console e il PID in ciascun messaggio, si dovrà usare: LOG_CONS | LOG_NDELAY | LOG_PID

Tabella 2. Facility di openlog()

Costante	Descrizione
LOG_AUTH	messaggi di sicurezza/autorizzazione (usa LOG_AUTHPRIV nei sistemi dove è definita quella costante)
LOG_AUTHPRIV	messaggi di sicurezza/autorizzazione (private)
LOG_CRON	clock daemon (cron e at)
LOG_DAEMON	altri demoni di sistema
LOG_KERN	messaggi del kernel
LOG_LOCAL0 ... LOG_LOCAL7	riservato per il locale
LOG_LPR	sottosistema line printer
LOG_MAIL	sottosistema mail
LOG_NEWS	sottosistema news di USENET
LOG_SYSLOG	messaggi generati internamente da syslogd
LOG_USER	messaggi generici user-level
LOG_UUCP	sottosistema UUCP

Vedere anche define_syslog_variables(), syslog() e closelog().

pfsockopen

(PHP 3 >= 3.0.7, PHP 4, PHP 5)

pfsockopen -- Apre una connessione persistente Internet o di tipo domain socket Unix

Descrizione

int pfsockopen ( string hostname, int port [, int errno [, string errstr [, int timeout]]] )

int syslog ( int priorità, string messaggio )

syslog() genera un messaggio di log che viene distribuito dal logger di sistema. priorità è la combinazione della facility e del livello, valori utilizzabili sono riportati nella prossima sezione. L'argomento rimanente è il messaggio da inviare, eccetto i due caratteri %m che vengono sostituiti dalla stringa del messaggio di errore (strerror) corrispondente all'attuale valore di errno.

Tabella 1. Priorità syslog() (in ordine discendente)

Costante	Descrizione
LOG_EMERG	sistema non utilizzabile
LOG_ALERT	azione da intraprendere immediatamente
LOG_CRIT	condizioni critiche
LOG_ERR	condizioni di errore
LOG_WARNING	condizioni di attenzione
LOG_NOTICE	condizione normale, ma significativa
LOG_INFO	messaggio di informazione
LOG_DEBUG	messaggio a livello di debug

Esempio 1. Uso di syslog()
<?php define_syslog_variables(); // apre il syslog, include l'ID del processo, invia il // log anche su standard error e fa uso di un meccanismo // di logging defiito dall'utente openlog("IlMioLog", LOG_PID | LOG_PERROR, LOG_LOCAL0); // un po' di codice if (client_autorizzato()) { // fa qualcosa } else { // client non autorizzato! // logga il tentativo $accesso = date("Y/m/d H:i:s"); syslog(LOG_WARNING,"Client non autorizzato: $accesso $REMOTE_ADDR ($HTTP_USER_AGENT)"); } closelog(); ?>
Per informazioni su come creare un gestore di log definito dall'utente, fare riferimento alla man page syslog.conf(5) di Unix. Ulteriori informazioni sulle facility di syslog e sulle sue opzioni possono essere trovate sulle macchine Unix nelle man page di syslog(3).

Su Windows NT, il servizio syslog è emulato usando Event Log.

Vedere anche define_syslog_variables(), openlog() e closelog().

XCI. Newt Functions

Introduzione

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.

Requisiti

This module uses the functions of the RedHat Newt library. You need libnewt version >= 0.51.0.

Installazione

In PHP 4 this PECL extensions source can be found in the ext/ directory within the PHP source or at the PECL link above. In order to use these functions you must compile CGI or CLI PHP with newt support by using the --with-newt[=DIR] configure option.

Nota: 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 followin configuration options: --with-curses-dir=/path/to/libcurses --with-slang-dir=/path/to/libslang

Tipi di risorse

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())

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

NEWT_COLORSET_ROOT (integer)
NEWT_COLORSET_BORDER (integer)
NEWT_COLORSET_WINDOW (integer)
NEWT_COLORSET_SHADOW (integer)
NEWT_COLORSET_TITLE (integer)
NEWT_COLORSET_BUTTON (integer)
NEWT_COLORSET_ACTBUTTON (integer)
NEWT_COLORSET_CHECKBOX (integer)
NEWT_COLORSET_ACTCHECKBOX (integer)
NEWT_COLORSET_ENTRY (integer)
NEWT_COLORSET_LABEL (integer)
NEWT_COLORSET_LISTBOX (integer)
NEWT_COLORSET_ACTLISTBOX (integer)
NEWT_COLORSET_TEXTBOX (integer)
NEWT_COLORSET_ACTTEXTBOX (integer)
NEWT_COLORSET_HELPLINE (integer)
NEWT_COLORSET_ROOTTEXT (integer)
NEWT_COLORSET_EMPTYSCALE (integer)
NEWT_COLORSET_FULLSCALE (integer)
NEWT_COLORSET_DISENTRY (integer)
NEWT_COLORSET_COMPACTBUTTON (integer)
NEWT_COLORSET_ACTSELLISTBOX (integer)
NEWT_COLORSET_SELLISTBOX (integer)
NEWT_ARG_LAST (integer)
NEWT_ARG_APPEND (integer)
NEWT_FLAGS_SET (integer)
NEWT_FLAGS_RESET (integer)
NEWT_FLAGS_TOGGLE (integer)
NEWT_FLAG_RETURNEXIT (integer)
NEWT_FLAG_HIDDEN (integer)
NEWT_FLAG_SCROLL (integer)
NEWT_FLAG_DISABLED (integer)
NEWT_FLAG_BORDER (integer)
NEWT_FLAG_WRAP (integer)
NEWT_FLAG_NOF12 (integer)
NEWT_FLAG_MULTIPLE (integer)
NEWT_FLAG_SELECTED (integer)
NEWT_FLAG_CHECKBOX (integer)
NEWT_FLAG_PASSWORD (integer)
NEWT_FLAG_SHOWCURSOR (integer)
NEWT_FD_READ (integer)
NEWT_FD_WRITE (integer)
NEWT_FD_EXCEPT (integer)
NEWT_CHECKBOXTREE_UNSELECTABLE (integer)
NEWT_CHECKBOXTREE_HIDE_BOX (integer)
NEWT_CHECKBOXTREE_COLLAPSED (integer)
NEWT_CHECKBOXTREE_EXPANDED (integer)
NEWT_CHECKBOXTREE_UNSELECTED (integer)
NEWT_CHECKBOXTREE_SELECTED (integer)
NEWT_LISTBOX_RETURNEXIT (integer)
NEWT_ENTRY_SCROLL (integer)
NEWT_ENTRY_HIDDEN (integer)
NEWT_ENTRY_RETURNEXIT (integer)
NEWT_ENTRY_DISABLED (integer)
NEWT_TEXTBOX_WRAP (integer)
NEWT_TEXTBOX_SCROLL (integer)
NEWT_FORM_NOF12 (integer)
NEWT_EXIT_HOTKEY (integer)
NEWT_EXIT_COMPONENT (integer)
NEWT_EXIT_FDREADY (integer)
NEWT_EXIT_TIMER (integer)
NEWT_KEY_TAB (integer)
NEWT_KEY_ENTER (integer)
NEWT_KEY_SUSPEND (integer)
NEWT_KEY_ESCAPE (integer)
NEWT_KEY_RETURN (integer)
NEWT_KEY_EXTRA_BASE (integer)
NEWT_KEY_UP (integer)
NEWT_KEY_DOWN (integer)
NEWT_KEY_LEFT (integer)
NEWT_KEY_RIGHT (integer)
NEWT_KEY_BKSPC (integer)
NEWT_KEY_DELETE (integer)
NEWT_KEY_HOME (integer)
NEWT_KEY_END (integer)
NEWT_KEY_UNTAB (integer)
NEWT_KEY_PGUP (integer)
NEWT_KEY_PGDN (integer)
NEWT_KEY_INSERT (integer)
NEWT_KEY_F1 (integer)
NEWT_KEY_F2 (integer)
NEWT_KEY_F3 (integer)
NEWT_KEY_F4 (integer)
NEWT_KEY_F5 (integer)
NEWT_KEY_F6 (integer)
NEWT_KEY_F7 (integer)
NEWT_KEY_F8 (integer)
NEWT_KEY_F9 (integer)
NEWT_KEY_F10 (integer)
NEWT_KEY_F11 (integer)
NEWT_KEY_F12 (integer)
NEWT_KEY_RESIZE (integer)
NEWT_ANCHOR_LEFT (integer)
NEWT_ANCHOR_RIGHT (integer)
NEWT_ANCHOR_TOP (integer)
NEWT_ANCHOR_BOTTOM (integer)
NEWT_GRID_FLAG_GROWX (integer)
NEWT_GRID_FLAG_GROWY (integer)
NEWT_GRID_EMPTY (integer)
NEWT_GRID_COMPONENT (integer)
NEWT_GRID_SUBGRID (integer)

Sommario
newt_bell -- Send a beep to the terminal
newt_button_bar --
newt_button --
newt_centered_window -- Open a centered window of the specified size
newt_checkbox_get_value --
newt_checkbox_set_flags --
newt_checkbox_set_value --
newt_checkbox_tree_add_item -- *
newt_checkbox_tree_find_item --
newt_checkbox_tree_get_current --
newt_checkbox_tree_get_entry_value --
newt_checkbox_tree_get_multi_selection --
newt_checkbox_tree_get_selection --
newt_checkbox_tree_multi --
newt_checkbox_tree_set_current --
newt_checkbox_tree_set_entry_value --
newt_checkbox_tree_set_entry --
newt_checkbox_tree_set_width --
newt_checkbox_tree --
newt_checkbox --
newt_clear_key_buffer -- Discards the contents of the terminal's input buffer without waiting for additional input
newt_cls --
newt_compact_button --
newt_component_add_callback --
newt_component_takes_focus --
newt_create_grid --
newt_cursor_off --
newt_cursor_on --
newt_delay --
newt_draw_form --
newt_draw_root_text -- Displays the string text at the position indicated
newt_entry_get_value --
newt_entry_set_filter --
newt_entry_set_flags --
newt_entry_set --
newt_entry --
newt_finished -- Uninitializes newt interface.
newt_form_add_component --
newt_form_add_components --
newt_form_add_host_key --
newt_form_get_current --
newt_form_run --
newt_form_set_background --
newt_form_set_height --
newt_form_set_size --
newt_form_set_timer --
newt_form_set_width --
newt_form_watch_fd --
newt_form --
newt_get_screen_size -- Fills in the passed references with the current size of the terminal
newt_grid_add_components_to_form --
newt_grid_basic_window --
newt_grid_free --
newt_grid_get_size --
newt_grid_h_close_stacked --
newt_grid_h_stacked --
newt_grid_place --
newt_grid_set_field --
newt_grid_simple_window --
newt_grid_v_close_stacked --
newt_grid_v_stacked --
newt_grid_wrapped_window_at --
newt_grid_wrapped_window --
newt_init -- Initialize newt
newt_label_set_text --
newt_label --
newt_listbox_append_entry --
newt_listbox_clear_selection --
newt_listbox_clear --
newt_listbox_delete_entry --
newt_listbox_get_current --
newt_listbox_get_selection --
newt_listbox_insert_entry --
newt_listbox_item_count --
newt_listbox_select_item --
newt_listbox_set_current_by_key --
newt_listbox_set_current --
newt_listbox_set_data --
newt_listbox_set_entry --
newt_listbox_set_width --
newt_listbox --
newt_listitem_get_data --
newt_listitem_set --
newt_listitem --
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 --
newt_radiobutton --
newt_redraw_help_line --
newt_reflow_text --
newt_refresh -- Updates modified portions of the screen
newt_resize_screen --
newt_resume -- Resume using the newt interface after calling newt_suspend()
newt_run_form --
newt_scale_set --
newt_scale --
newt_scrollbar_set --
newt_set_help_callback --
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_texbox_set_text --
newt_textbox_get_num_lines --
newt_textbox_reflowed --
newt_textbox_set_height --
newt_textbox --
newt_vertical_scrollbar --
newt_wait_for_key -- Doesn't return until a key has been pressed
newt_win_choice --
newt_win_entries --
newt_win_menu --
newt_win_message --
newt_win_messagev --
newt_win_ternary --

newt_bell

(PECL)

newt_bell -- Send a beep to the terminal

Descrizione

void newt_bell ( void )

This function sends a beep to the terminal.

Nota: Depending on the terminal's settings, this been may or may not be audible.

newt_button_bar

(PECL)

newt_button_bar --

Descrizione

resource newt_button_bar ( array &buttons )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Elenco dei parametri

buttons: Its description

Valori restituiti

What the function returns, first on success, then on failure. See also the &return.success; entity

newt_button

(PECL)

newt_button --

Descrizione

resource newt_button ( int left, int top, string text )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Elenco dei parametri

left: Its description
top: Its description
text: Its description

Valori restituiti

What the function returns, first on success, then on failure. See also the &return.success; entity

newt_centered_window

(PECL)

newt_centered_window -- Open a centered window of the specified size

Descrizione

int newt_centered_window ( int width, int height [, string title] )

Open a centered window of the specified size.

Elenco dei parametri

width: Window width
height: Window height
title: Window title

Valori restituiti

Undefined value.

Vedere anche:

newt_pop_window()

newt_open_window()

newt_checkbox_get_value

(PECL)

newt_checkbox_get_value --

Descrizione

string newt_checkbox_get_value ( resource checkbox )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Elenco dei parametri

checkbox: Its description

Valori restituiti

What the function returns, first on success, then on failure. See also the &return.success; entity

newt_checkbox_set_flags

(PECL)

newt_checkbox_set_flags --

Descrizione

void newt_checkbox_set_flags ( resource checkbox, int flags, int sense )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Elenco dei parametri

checkbox: Its description
flags: Its description
sense: Its description

Valori restituiti

What the function returns, first on success, then on failure. See also the &return.success; entity

newt_checkbox_set_value

(PECL)

newt_checkbox_set_value --

Descrizione

void newt_checkbox_set_value ( resource checkbox, string value )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Elenco dei parametri

checkbox: Its description
value: Its description

Valori restituiti

What the function returns, first on success, then on failure. See also the &return.success; entity

newt_checkbox_tree_add_item

(PECL)

newt_checkbox_tree_add_item -- *

Descrizione

void newt_checkbox_tree_add_item ( resource checkboxtree, string text, mixed data, int flags, array indexes )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Elenco dei parametri

checkboxtree: Its description
text: Its description
data: Its description
flags: Its description
indexes: Its description

Valori restituiti

What the function returns, first on success, then on failure. See also the &return.success; entity

newt_checkbox_tree_find_item

(PECL)

newt_checkbox_tree_find_item --

Descrizione

array newt_checkbox_tree_find_item ( resource checkboxtree, mixed data )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Elenco dei parametri

checkboxtree: Its description
data: Its description

Valori restituiti

What the function returns, first on success, then on failure. See also the &return.success; entity

newt_checkbox_tree_get_current

(PECL)

newt_checkbox_tree_get_current --

Descrizione

mixed newt_checkbox_tree_get_current ( resource checkboxtree )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Elenco dei parametri

checkboxtree: Its description

Valori restituiti

What the function returns, first on success, then on failure. See also the &return.success; entity

newt_checkbox_tree_get_entry_value

(PECL)

newt_checkbox_tree_get_entry_value --

Descrizione

string newt_checkbox_tree_get_entry_value ( resource checkboxtree, mixed data )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Elenco dei parametri

checkboxtree: Its description
data: Its description

Valori restituiti

What the function returns, first on success, then on failure. See also the &return.success; entity

newt_checkbox_tree_get_multi_selection

(PECL)

newt_checkbox_tree_get_multi_selection --

Descrizione

array newt_checkbox_tree_get_multi_selection ( resource checkboxtree, string seqnum )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Elenco dei parametri

checkboxtree: Its description
seqnum: Its description

Valori restituiti

What the function returns, first on success, then on failure. See also the &return.success; entity

newt_checkbox_tree_get_selection

(PECL)

newt_checkbox_tree_get_selection --

Descrizione

array newt_checkbox_tree_get_selection ( resource checkboxtree )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Elenco dei parametri

checkboxtree: Its description

Valori restituiti

What the function returns, first on success, then on failure. See also the &return.success; entity

newt_checkbox_tree_multi

(PECL)

newt_checkbox_tree_multi --

Descrizione

resource newt_checkbox_tree_multi ( int left, int top, int height, string seq [, int flags] )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Elenco dei parametri

left: Its description
top: Its description
height: Its description
seq: Its description
flags: Its description

Valori restituiti

What the function returns, first on success, then on failure. See also the &return.success; entity

newt_checkbox_tree_set_current

(PECL)

newt_checkbox_tree_set_current --

Descrizione

void newt_checkbox_tree_set_current ( resource checkboxtree, mixed data )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Elenco dei parametri

checkboxtree: Its description
data: Its description

Valori restituiti

What the function returns, first on success, then on failure. See also the &return.success; entity

newt_checkbox_tree_set_entry_value

(PECL)

newt_checkbox_tree_set_entry_value --

Descrizione

void newt_checkbox_tree_set_entry_value ( resource checkboxtree, mixed data, string value )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Elenco dei parametri

checkboxtree: Its description
data: Its description
value: Its description

Valori restituiti

What the function returns, first on success, then on failure. See also the &return.success; entity

newt_checkbox_tree_set_entry

(PECL)

newt_checkbox_tree_set_entry --

Descrizione

void newt_checkbox_tree_set_entry ( resource checkboxtree, mixed data, string text )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Elenco dei parametri

checkboxtree: Its description
data: Its description
text: Its description

Valori restituiti

What the function returns, first on success, then on failure. See also the &return.success; entity

newt_checkbox_tree_set_width

(PECL)

newt_checkbox_tree_set_width --

Descrizione

void newt_checkbox_tree_set_width ( resource checkbox_tree, int width )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Elenco dei parametri

checkbox_tree: Its description
width: Its description

Valori restituiti

What the function returns, first on success, then on failure. See also the &return.success; entity

newt_checkbox_tree

(PECL)

newt_checkbox_tree --

Descrizione

resource newt_checkbox_tree ( int left, int top, int height [, int flags] )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Elenco dei parametri

left: Its description
top: Its description
height: Its description
flags: Its description

Valori restituiti

What the function returns, first on success, then on failure. See also the &return.success; entity

newt_checkbox

(PECL)

newt_checkbox --

Descrizione

resource newt_checkbox ( int left, int top, string text, string def_value [, string seq] )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Elenco dei parametri

left: Its description
top: Its description
text: Its description
def_value: Its description
seq: Its description

Valori restituiti

What the function returns, first on success, then on failure. See also the &return.success; entity

newt_clear_key_buffer

(PECL)

newt_clear_key_buffer -- Discards the contents of the terminal's input buffer without waiting for additional input

Descrizione

void newt_clear_key_buffer ( void )

Discards the contents of the terminal's input buffer without waiting for additional input.

Vedere anche:

newt_wait_for_key()

newt_cls

(PECL)

newt_cls --

Descrizione

void newt_cls ( void )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Valori restituiti

What the function returns, first on success, then on failure. See also the &return.success; entity

newt_cursor_on

(PECL)

newt_cursor_on --

Descrizione

void newt_cursor_on ( void )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Elenco dei parametri

Valori restituiti

What the function returns, first on success, then on failure. See also the &return.success; entity

newt_delay

(PECL)

newt_delay --

Descrizione

void newt_delay ( int microseconds )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Elenco dei parametri

microseconds: Its description

Valori restituiti

What the function returns, first on success, then on failure. See also the &return.success; entity

newt_draw_form

(PECL)

newt_draw_form --

Descrizione

void newt_draw_form ( resource form )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Elenco dei parametri

form: Its description

Valori restituiti

What the function returns, first on success, then on failure. See also the &return.success; entity

newt_draw_root_text

(PECL)

newt_draw_root_text -- Displays the string text at the position indicated

Descrizione

void newt_draw_root_text ( int left, int top, string text )

Displays the string text at the position indicated.

Elenco dei parametri

left: Column number
Nota: If left is negative, the position is measured from the opposite side of the screen.
top: Line number
Nota: If top is negative, the position is measured from the opposite side of the screen.
text: Text to display.

Esempi

Esempio 1. A newt_draw_root_text() example
This code demonstrates drawing of titles in the both corners of the screen.
<? 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(); ?>

Vedere anche:

newt_push_help_line()

newt_pop_help_line()

newt_entry_get_value

(PECL)

newt_entry_get_value --

Descrizione

string newt_entry_get_value ( resource entry )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Elenco dei parametri

entry: Its description

Valori restituiti

What the function returns, first on success, then on failure. See also the &return.success; entity

newt_entry_set_filter

(PECL)

newt_entry_set_filter --

Descrizione

void newt_entry_set_filter ( resource entry, callback filter, mixed data )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Elenco dei parametri

entry: Its description
filter: Its description
data: Its description

Valori restituiti

What the function returns, first on success, then on failure. See also the &return.success; entity

newt_entry_set_flags

(PECL)

newt_entry_set_flags --

Descrizione

void newt_entry_set_flags ( resource entry, int flags, int sense )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Elenco dei parametri

entry: Its description
flags: Its description
sense: Its description

Valori restituiti

What the function returns, first on success, then on failure. See also the &return.success; entity

newt_entry_set

(PECL)

newt_entry_set --

Descrizione

void newt_entry_set ( resource entry, string value [, bool cursor_at_end] )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Elenco dei parametri

entry: Its description
value: Its description
cursor_at_end: Its description

Valori restituiti

What the function returns, first on success, then on failure. See also the &return.success; entity

newt_entry

(PECL)

newt_entry --

Descrizione

resource newt_entry ( int left, int top, int width [, string init_value [, int flags]] )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Elenco dei parametri

left: Its description
top: Its description
width: Its description
init_value: Its description
flags: Its description

Valori restituiti

What the function returns, first on success, then on failure. See also the &return.success; entity

newt_finished

(PECL)

newt_finished -- Uninitializes newt interface.

Descrizione

void newt_finished ( void )

vert_bar: Its description
help: Its description
flags: Its description

Valori restituiti

What the function returns, first on success, then on failure. See also the &return.success; entity

newt_get_screen_size

(PECL)

newt_get_screen_size -- Fills in the passed references with the current size of the terminal

Descrizione

void newt_get_screen_size ( int &cols, int &rows )

Fills in the passed references with the current size of the terminal.

Elenco dei parametri

cols: Number of columns in the terminal
rows: Number of rows in the terminal

Elenco dei parametri

grid: Its description
title: Its description

Valori restituiti

What the function returns, first on success, then on failure. See also the &return.success; entity

newt_init

(PECL)

newt_init -- Initialize newt

Descrizione

void newt_init ( void )

left: Its description
top: Its description
text: Its description
is_default: Its description
prev_item: Its description
data: Its description
flags: Its description

Valori restituiti

What the function returns, first on success, then on failure. See also the &return.success; entity

newt_open_window

(PECL)

newt_open_window -- Open a window of the specified size and position

Descrizione

void newt_open_window ( int left, int top, int width, int height [, string title] )

Open a window of the specified size and position.

Elenco dei parametri

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

Valori restituiti

Undefined value.

Vedere anche:

newt_pop_window()

newt_centered_window()

newt_pop_help_line

(PECL)

newt_pop_help_line -- Replaces the current help line with the one from the stack

Descrizione

void newt_pop_help_line ( void )

Replaces the current help line with the one from the stack.

Nota: It's important not to call to newt_pop_help_line() more then newt_push_help_line().

Vedere anche:

newt_push_help_line()

newt_pop_window

(PECL)

newt_pop_window -- Removes the top window from the display

Descrizione

void newt_pop_window ( void )

Removes the top window from the display, and redraws the display areas which the window overwrote.

Vedere anche:

newt_open_window()

newt_centered_window()

newt_push_help_line

(PECL)

newt_push_help_line -- Saves the current help line on a stack, and displays the new line

Descrizione

void newt_push_help_line ( [string text] )

Saves the current help line on a stack, and displays the new line.

Elenco dei parametri

text: New help text message
Nota: If not specified, the help line is cleared.

Vedere anche:

newt_pop_help_line()

newt_radio_get_current

(PECL)

newt_radio_get_current --

Descrizione

resource newt_radio_get_current ( resource set_member )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Elenco dei parametri

set_member: Its description

Valori restituiti

What the function returns, first on success, then on failure. See also the &return.success; entity

newt_radiobutton

(PECL)

newt_radiobutton --

Descrizione

resource newt_radiobutton ( int left, int top, string text, bool is_default [, resource prev_button] )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Elenco dei parametri

left: Its description
top: Its description
text: Its description
is_default: Its description
prev_button: Its description

Valori restituiti

What the function returns, first on success, then on failure. See also the &return.success; entity

newt_redraw_help_line

(PECL)

newt_redraw_help_line --

Descrizione

void newt_redraw_help_line ( void )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Elenco dei parametri

Valori restituiti

What the function returns, first on success, then on failure. See also the &return.success; entity

newt_reflow_text

(PECL)

newt_reflow_text --

Descrizione

string newt_reflow_text ( string text, int width, int flex_down, int flex_up, int &actual_width, int &actual_height )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Elenco dei parametri

text: Its description
width: Its description
flex_down: Its description
flex_up: Its description
actual_width: Its description
actual_height: Its description

Valori restituiti

What the function returns, first on success, then on failure. See also the &return.success; entity

newt_refresh

(PECL)

newt_refresh -- Updates modified portions of the screen

Descrizione

void newt_refresh ( void )

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.

newt_resize_screen

(PECL)

newt_resize_screen --

Descrizione

void newt_resize_screen ( [bool redraw] )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Elenco dei parametri

redraw: Its description

Valori restituiti

What the function returns, first on success, then on failure. See also the &return.success; entity

newt_resume

(PECL)

newt_resume -- Resume using the newt interface after calling newt_suspend()

Descrizione

void newt_resume ( void )

function: Its description

Valori restituiti

What the function returns, first on success, then on failure. See also the &return.success; entity

newt_set_suspend_callback

(PECL)

newt_set_suspend_callback -- Set a callback function which gets invoked when user presses the suspend key

Descrizione

void newt_set_suspend_callback ( callback function, mixed data )

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.

Elenco dei parametri

function: A callback function, which accepts one argument: data
data: This data is been passed to the callback function

Vedere anche:

newt_suspend()

newt_resume()

newt_suspend

(PECL)

newt_suspend -- Tells newt to return the terminal to its initial state

Descrizione

void newt_suspend ( void )

left: Its description
top: Its description
height: Its description
normal_colorset: Its description
thumb_colorset: Its description

Valori restituiti

What the function returns, first on success, then on failure. See also the &return.success; entity

newt_wait_for_key

(PECL)

newt_wait_for_key -- Doesn't return until a key has been pressed

Descrizione

void newt_wait_for_key ( void )

title: Its description
button1_text: Its description
button2_text: Its description
button3_text: Its description
format: Its description
args: Its description

Valori restituiti

What the function returns, first on success, then on failure. See also the &return.success; entity

XCII. NSAPI-specific Functions

Introduzione

These functions are only available when running PHP as a NSAPI module in Netscape/iPlanet/SunONE webservers.

Installazione

For PHP installation on Netscape/iPlanet/SunONE webservers see the NSAPI section (UNIX, Windows) in the installation chapter.

Configurazione di Runtime

The behaviour of the NSAPI PHP module is affected by settings in php.ini. Configuration settings from php.ini may be overridden by additional parameters to the php4_execute call in obj.conf

Tabella 1. NSAPI configuration options

Name	Default	Changeable	Changelog
nsapi.read_timeout	"60"	PHP_INI_ALL	Available since PHP 4.3.3.

Per maggiori dettagli sulle costanti PHP_INI_* vedere Appendice G.

Breve descrizione dei parametri di configurazione.

nsapi.read_timeout integer: Sets the time in seconds the plugin is waiting for POST data from the client.

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

Questa estensione non definisce alcuna costante.

Vedere anche:

NSAPI implements a subset of the functions from the Apache module for maximum compatibility.

Tabella 2. Apache functions implemented by NSAPI

Apache function (only as alias)	NSAPI function	Description
apache_request_headers()	nsapi_request_headers()	Fetch all HTTP request headers
apache_response_headers()	nsapi_response_headers()	Fetch all HTTP response headers
getallheaders()	nsapi_request_headers()	Fetch all HTTP request headers
virtual()	nsapi_virtual()	Make NSAPI sub-request

Sommario
nsapi_request_headers -- Fetch all HTTP request headers
nsapi_response_headers -- Fetch all HTTP response headers
nsapi_virtual -- Perform an NSAPI sub-request

nsapi_request_headers

(PHP 4 >= 4.3.3, PHP 5)

nsapi_request_headers -- Fetch all HTTP request headers

Descrizione

array nsapi_request_headers ( void )

nsapi_request_headers() gets all the HTTP headers in the current request. This is only supported when PHP runs as a NSAPI module.

Nota: Prior to PHP 4.3.3, getallheaders() was only available for the Apache servers. After PHP 4.3.3, getallheaders() is an alias for nsapi_request_headers() if you use the NSAPI module.

Nota: You can also get at the value of the common CGI variables by reading them from the $_SERVER superglobal, which works whether or not you are using PHP as a NSAPI module.

Valori restituiti

Returns an associative array with all the HTTP headers.

Esempi

Esempio 1. nsapi_request_headers() example
<?php $headers = nsapi_request_headers(); foreach ($headers as $header => $value) { echo "$header: $value <br />\n"; } ?>

nsapi_response_headers

(PHP 4 >= 4.3.3, PHP 5)

nsapi_response_headers -- Fetch all HTTP response headers

Descrizione

array nsapi_response_headers ( void )

Gets all the NSAPI response headers.

Valori restituiti

Returns an associative array with all the NSAPI response headers.

Vedere anche:

nsapi_request_headers()

headers_sent()

nsapi_virtual

(PHP 4 >= 4.3.3, PHP 5)

nsapi_virtual -- Perform an NSAPI sub-request

Descrizione

bool nsapi_virtual ( string uri )

nsapi_virtual() is an NSAPI-specific function which is equivalent to  in SSI (.shtml files). It does an NSAPI sub-request. It is useful for including CGI scripts or .shtml files, or anything else that you'd parse through webserver.

To run the sub-request, all buffers are terminated and flushed to the browser, pending headers are sent too.

You cannot make recursive requests with this function to other PHP scripts. If you want to include PHP scripts, use include() or require().

Nota: This function depends on a undocumented feature of the Netscape/iPlanet/SunONE webservers. Use phpinfo() to determine if it is available. In the Unix environment it should always work, in windows it depends on the name of a ns-httpdXX.dll file.
Read the note about subrequests in the NSAPI section (UNIX, Windows) if you experience this problem.

Elenco dei parametri

uri: The URI of the script.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

XCIII. Object Aggregation/Composition Functions

Avvertimento

Introduzione

In Object Oriented Programming, it is common to see the composition of simple classes (and/or instances) into a more complex one. This is a flexible strategy for building complicated objects and object hierarchies and can function as a dynamic alternative to multiple inheritance. There are two ways to perform class (and/or object) composition depending on the relationship between the composed elements: Association and Aggregation.

An Association is a composition of independently constructed and externally visible parts. When we associate classes or objects, each one keeps a reference to the ones it is associated with. When we associate classes statically, one class will contain a reference to an instance of the other class. For example:
Esempio 1. Class association
<?php class DateTime { function DateTime() { // empty constructor } function now() { return date("Y-m-d H:i:s"); } } class Report { var $_dt; // more properties ... function Report() { $this->_dt = new DateTime(); // initialization code ... } function generateReport() { $dateTime = $this->_dt->now(); // more code ... } // more methods ... } $rep = new Report(); ?>
We can also associate instances at runtime by passing a reference in a constructor (or any other method), which allow us to dynamically change the association relationship between objects. We will modify the example above to illustrate this point:
Esempio 2. Object association
<?php class DateTime { // same as previous example } class DateTimePlus { var $_format; function DateTimePlus($format="Y-m-d H:i:s") { $this->_format = $format; } function now() { return date($this->_format); } } class Report { var $_dt; // we'll keep the reference to DateTime here // more properties ... function Report() { // do some initialization } function setDateTime(&$dt) { $this->_dt =& $dt; } function generateReport() { $dateTime = $this->_dt->now(); // more code ... } // more methods ... } $rep = new Report(); $dt = new DateTime(); $dtp = new DateTimePlus("l, F j, Y (h:i:s a, T)"); // generate report with simple date for web display $rep->setDateTime(&$dt); echo $rep->generateReport(); // later on in the code ... // generate report with fancy date $rep->setDateTime(&$dtp); $output = $rep->generateReport(); // save $output in database // ... etc ... ?>

Aggregation, on the other hand, implies encapsulation (hidding) of the parts of the composition. We can aggregate classes by using a (static) inner class (PHP does not yet support inner classes), in this case the aggregated class definition is not accessible, except through the class that contains it. The aggregation of instances (object aggregation) involves the dynamic creation of subobjects inside an object, in the process, expanding the properties and methods of that object.

Object aggregation is a natural way of representing a whole-part relationship, (for example, molecules are aggregates of atoms), or can be used to obtain an effect equivalent to multiple inheritance, without having to permanently bind a subclass to two or more parent classes and their interfaces. In fact object aggregation can be more flexible, in which we can select what methods or properties to "inherit" in the aggregated object.

Esempi

We define 3 classes, each implementing a different storage method:

Esempio 3. storage_classes.inc
<?php class FileStorage { var $data; function FileStorage($data) { $this->data = $data; } function write($name) { $fp = fopen(name, "w"); fwrite($fp, $this->data); fclose($data); } } class WDDXStorage { var $data; var $version = "1.0"; var $_id; // "private" variable function WDDXStorage($data) { $this->data = $data; $this->_id = $this->_genID(); } function store() { if ($this->_id) { $pid = wddx_packet_start($this->_id); wddx_add_vars($pid, "this->data"); $packet = wddx_packet_end($pid); } else { $packet = wddx_serialize_value($this->data); } $dbh = dba_open("varstore", "w", "gdbm"); dba_insert(md5(uniqid("", true)), $packet, $dbh); dba_close($dbh); } // a private method function _genID() { return md5(uniqid(rand(), true)); } } class DBStorage { var $data; var $dbtype = "mysql"; function DBStorage($data) { $this->data = $data; } function save() { $dbh = mysql_connect(); mysql_select_db("storage", $dbh); $serdata = serialize($this->data); mysql_query("insert into vars ('$serdata',now())", $dbh); mysql_close($dbh); } } ?>

We then instantiate a couple of objects from the defined classes, and perform some aggregations and deaggregations, printing some object information along the way:

Esempio 4. test_aggregation.php
<?php include "storageclasses.inc"; // some utilty functions function p_arr($arr) { foreach ($arr as $k => $v) $out[] = "\t$k => $v"; return implode("\n", $out); } function object_info($obj) { $out[] = "Class: " . get_class($obj); foreach (get_object_vars($obj) as $var=>$val) { if (is_array($val)) { $out[] = "property: $var (array)\n" . p_arr($val); } else { $out[] = "property: $var = $val"; } } foreach (get_class_methods($obj) as $method) { $out[] = "method: $method"; } return implode("\n", $out); } $data = array(M_PI, "kludge != cruft"); // we create some basic objects $fs = new FileStorage($data); $ws = new WDDXStorage($data); // print information on the objects echo "\$fs object\n"; echo object_info($fs) . "\n"; echo "\n\$ws object\n"; echo object_info($ws) . "\n"; // do some aggregation echo "\nLet's aggregate \$fs to the WDDXStorage class\n"; aggregate($fs, "WDDXStorage"); echo "\$fs object\n"; echo object_info($fs) . "\n"; echo "\nNow let us aggregate it to the DBStorage class\n"; aggregate($fs, "DBStorage"); echo "\$fs object\n"; echo object_info($fs) . "\n"; echo "\nAnd finally deaggregate WDDXStorage\n"; deaggregate($fs, "WDDXStorage"); echo "\$fs object\n"; echo object_info($fs) . "\n"; ?>

We will now consider the output to understand some of the side-effects and limitation of object aggregation in PHP. First, the newly created $fs and $ws objects give the expected output (according to their respective class declaration). Note that for the purposes of object aggregation, private elements of a class/object begin with an underscore character ("_"), even though there is not real distinction between public and private class/object elements in PHP.

$fs object
Class: filestorage
property: data (array)
    0 => 3.1415926535898
    1 => kludge != cruft
method: filestorage
method: write

$ws object
Class: wddxstorage
property: data (array)
    0 => 3.1415926535898
    1 => kludge != cruft
property: version = 1.0
property: _id = ID::9bb2b640764d4370eb04808af8b076a5
method: wddxstorage
method: store
method: _genid

We then aggregate $fs with the WDDXStorage class, and print out the object information. We can see now that even though nominally the $fs object is still of FileStorage, it now has the property $version, and the method store(), both defined in WDDXStorage. One important thing to note is that it has not aggregated the private elements defined in the class, which are present in the $ws object. Also absent is the constructor from WDDXStorage, which will not be logical to aggegate.

Let's aggregate $fs to the WDDXStorage class
$fs object
Class: filestorage
property: data (array)
    0 => 3.1415926535898
    1 => kludge != cruft
property: version = 1.0
method: filestorage
method: write
method: store

The process of aggregation is cumulative, so when we aggregate $fs with the class DBStorage, generating an object that can use the storage methods of all the defined classes.

Now let us aggregate it to the DBStorage class
$fs object
Class: filestorage
property: data (array)
    0 => 3.1415926535898
    1 => kludge != cruft
property: version = 1.0
property: dbtype = mysql
method: filestorage
method: write
method: store
method: save

Finally, the same way we aggregated properties and methods dynamically, we can also deaggregate them from the object. So, if we deaggregate the class WDDXStorage from $fs, we will obtain:

And deaggregate the WDDXStorage methods and properties
$fs object
Class: filestorage
property: data (array)
    0 => 3.1415926535898
    1 => kludge != cruft
property: dbtype = mysql
method: filestorage
method: write
method: save

One point that we have not mentioned above, is that the process of aggregation will not override existing properties or methods in the objects. For example, the class FileStorage defines a $data property, and the class WDDXStorage also defines a similar property which will not override the one in the object acquired during instantiation from the class FileStorage.

Sommario
aggregate_info -- Returns an associative array of the methods and properties from each class that has been aggregated to the object
aggregate_methods_by_list -- Selective dynamic class methods aggregation to an object
aggregate_methods_by_regexp -- Selective class methods aggregation to an object using a regular expression
aggregate_methods -- Dynamic class and object aggregation of methods
aggregate_properties_by_list -- Selective dynamic class properties aggregation to an object
aggregate_properties_by_regexp -- Selective class properties aggregation to an object using a regular expression
aggregate_properties -- Dynamic aggregation of class properties to an object
aggregate -- Dynamic class and object aggregation of methods and properties
aggregation_info -- Alias di aggregate_info()
deaggregate -- Removes the aggregated methods and properties from an object

(PHP 4 >= 4.2.0)

aggregate_properties_by_list -- Selective dynamic class properties aggregation to an object

Description

void aggregate_properties_by_list ( object object, string class_name, array properties_list [, bool exclude] )

Aggregates properties from a class to an existing object using a list of property names. The optional parameter exclude is used to decide whether the list contains the names of class properties to include in the aggregation (i.e. exclude is FALSE, which is the default value), or to exclude from the aggregation (exclude is TRUE).

The properties whose names start with an underscore character (_), which are considered private to the aggregated class, are always excluded.

aggregate_properties_by_regexp

(PHP 4 >= 4.2.0)

aggregate_properties_by_regexp -- Selective class properties aggregation to an object using a regular expression

Description

void aggregate_properties_by_regexp ( object object, string class_name, string regexp [, bool exclude] )

This function is an alias of: aggregate_info().

deaggregate

(PHP 4 >= 4.2.0)

deaggregate -- Removes the aggregated methods and properties from an object

Description

void deaggregate ( object object [, string class_name] )

Removes the methods and properties from classes that were aggregated to an object. If the optional class_name parameters is passed, only those methods and properties defined in that class are removed, otherwise all aggregated methods and properties are eliminated.

XCIV. Proprietà object e method call overloading

Introduzione

Lo scopo di questa estensione è di permettere l'overloading delle proprietà di accesso agli oggetti e dei metodi di chiamata. Solo una funzione è definita in questa estensione, overload() che prende il nome dalla classe che ha questa funzionalità abilitata. La classe nominata ha da definire metodi appropriati se vuole avere questa funzionalità: __get(), __set() and __call() rispettivamente per ricevere/impostare una proprietà, o chiamare un metodo. Questa strada del sovraccarico può essere selettiva. Dentro queste funzioni handler l'overloading è disabilitato così si può accedere alle proprietà dell'oggetto normalmente.

Avvertimento

Questo modulo non è parte di PHP 5. Php 5 gestisce le chiamate __get(), __set() and __call() in modo nativo. Vedere la pagina l'overload in PHP 5 per maggiori dettagli.

Requisiti

Non sono necessarie librerie esterne per utilizzare questo modulo.

Installazione

Per potere utilizzare queste funzioni occorre compilare il PHP con --enable-overload. A partire dal PHP 4.3.0 questo modulo è abilitato per default. Si può disabilitare il supporto overload tramite --disable--overload.

La versione per Windows di PHP ha già compilato il supporto per questo modulo. Non occorre caricare alcun modulo addizionale per potere utilizzare queste funzioni.

Nota: Il supporto per questo modulo è compilato per default a partire dal PHP 4.3.0.

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

Questa estensione non definisce alcuna costante.

Esempi

Alcuni semplici esempi sull'uso della funzione overload()
Esempio 1. Overloading di una classe PHP
<?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: 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 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); ?>

Sommario
overload -- Abilita le proprietà e il method call overloading per una classe

overload

(PHP 4 >= 4.2.0)

overload -- Abilita le proprietà e il method call overloading per una classe

Descrizione

void overload ( [string class_name] )

La funzione overload() abiliterà la proprietà e il method call overloading per una classe identificata dal parametro class_name. Guarda un esempio nella sezione di introduzione di questa parte..

XCV. Funzioni Oracle 8

Introduzione

Queste funzioni permettono di accedere ai database Oracle9, Oracle8 e Oracle7. Usano la Oracle Call Interface (OCI).

Questa estensione è più flessibile della estensione precedente di Oracle. Supporta il binding di variabili PHP locali e globali ai segnaposto Oracle, ha pieno supporto di LOB, FILE e ROWID e permette di utilizzare variabili di definizione personalizzabili. Si raccomanda di utilizzare questa estensione al posto della vecchia estensione quando possibile;

Requisiti

Occorre avere installate le librerie client di Oracle per utilizzare questa estensione. Gli utenti Windows necessitano almeno della versione 8.1 di Oracle per utilizzare la dll php_oci8.dll.

Prima di usare questa estensione, occorre sincerarsi di aver impostato le variabili d'ambiente per l'utente Oracle, come pure per l'utente del server web. Le variabili che potrebbero necessitare l'impostazione sono le seguenti:

ORACLE_HOME
ORACLE_SID
LD_PRELOAD
LD_LIBRARY_PATH
NLS_LANG
ORA_NLS33

Dopo aver impostato le variabili d'ambiente per l'utente del server web, occorre sicerarsi di aver aggiunto anche l'utente stesso (nobody, www) al gruppo oracle.

Se il server web non parte o va in blocco: Controllare che apache sia linkato con la libreria pthread:
# 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)
Se la libpthread non compare nell'elenco, occorre reinstallare Apache:
# cd /usr/src/apache_1.3.xx
# make clean
# LIBS=-lpthread ./config.status
# make
# make install
Si noti che su alcuni sistemi, come ad esempio UnixWare, la libreria si chiama libthread invece di libpthread. PHP e Apache devono essere configurati con EXTRA_LIBS=-lthread.

Installazione

Si deve compilare PHP con l'opzione --with-oci8[=DIR], dove DIR è di default il contenuto della variabile di ambiente ORACLE_HOME.

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Tipi di risorse

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

OCI_DEFAULT (integer): Modalità di esecuzione dello statement. Non viene eseguito il commit automatico utilizzando questa modalità.
OCI_DESCRIBE_ONLY (integer): Modalità di esecuzione dello statement. Utilizzare questa modalità se non si vuole eseguire la query, ma solamente ricevere la descrizione della select list.
OCI_COMMIT_ON_SUCCESS (integer): Modalità di esecuzione dello statement. Vene eseguito automaticamente il commit dello statement dopo la chiamata della oci_execute().
OCI_EXACT_FETCH (integer): Modalità di recupero dati dello statement. Utilizzato quando l'applicazione conosce in anticipo quante righe verranno recuperate. Questa modalità disattiva il prefetching negli Oracle release 8 o successivi. Il cursore viene eliminato dopo che le sono state caricate e ciò può determinare un utilizzo ridotto delle risorse del server.
OCI_SYSDATE (integer)
OCI_B_BFILE (integer): Utilizzato con oci_bind_by_name() quando si collegano i BFILE.
OCI_B_CFILEE (integer): Utilizzato con oci_bind_by_name() quando si collegano i CFILE.
OCI_B_CLOB (integer): Utilizzato con oci_bind_by_name() quando si collegano i CLOB.
OCI_B_BLOB (integer): Utilizzato con oci_bind_by_name() quando si collegano i BLOB.
OCI_B_ROWID (integer): Utilizzato con oci_bind_by_name() quando si collegano i ROWID.
OCI_B_CURSOR (integer): Utilizzato con oci_bind_by_name() quando si collegano i cursori, precedentemente allocati con oci_new_descriptor().
OCI_B_NTY (integer): Utilizzato con oci_bind_by_name() quando si collegano i named data type.
OCI_B_BIN (integer)
SQLT_BFILEE (integer): Alias di OCI_B_BFILE.
SQLT_CFILEE (integer): Alias di OCI_B_CFILEE.
SQLT_CLOB (integer): Alias di OCI_B_CLOB.
SQLT_BLOB (integer): Alias di OCI_B_BLOB.
SQLT_RDD (integer): Alias di OCI_B_ROWID.
SQLT_NTY (integer): Alias di OCI_B_NTY.
OCI_FETCHSTATEMENT_BY_COLUMN (integer): Modalità di default di oci_fetch_all().
OCI_FETCHSTATEMENT_BY_ROW (integer): Modalità alternativa di oci_fetch_all().
OCI_ASSOC (integer): Utilizzato con oci_fetch_all() e oci_fetch_array() per ottenere un array associative come risultato.
OCI_NUM (integer): Utilizzato con oci_fetch_all() e oci_fetch_array() per ottenere un array enumerativo come risultato.
OCI_BOTH (integer): Utilizzato con oci_fetch_all() e oci_fetch_array() per ottenere un array con indici sia associativi che numerici.
OCI_RETURN_NULLS (integer): Utilizzato con oci_fetch_array() per ottenere elementi dell'array vuoti se il valore del campo è NULL.
OCI_RETURN_LOBS (integer): Utilizzato con oci_fetch_array() per ottenere il valore del LOB invece del suo descrittore.
OCI_DTYPE_FILE (integer): Questo flag ordina a oci_new_descriptor() di inizializzare un nuovo descrittore di FILE.
OCI_DTYPE_LOB (integer): Questo flag ordina a oci_new_descriptor() di inizializzare un nuovo descrittore di LOB.
OCI_DTYPE_ROWID (integer): Questo flag ordina a oci_new_descriptor() di inizializzare un nuovo descrittore di ROWID.
OCI_D_FILE (integer): Alias di OCI_DTYPE_FILE.
OCI_D_LOB (integer): Alias di OCI_DTYPE_LOB.
OCI_D_ROWID (integer): Alias di OCI_DTYPE_ROWID.

Esempi

Esempio 1. Trucchi OCI
<?php // by sergo at bacup dot ru // Usare l'opzione OCI_DEFAULT nel comando execute per ritardare l'esicuzione OCIExecute($stmt, OCI_DEFAULT); // per ricevere i dati utilizzare (dopo il fetch): $result = OCIResult($stmt, $n); if (is_object($result)) $result = $result->load(); // come comandi INSERT o UPDATE usare: $sql = "insert into table (field1, field2) values (field1 = 'value', field2 = empty_clob()) returning field2 into :field2"; OCIParse($conn, $sql); $clob = OCINewDescriptor($conn, OCI_D_LOB); OCIBindByName($stmt, ":field2", &$clob, -1, OCI_B_CLOB); OCIExecute($stmt, OCI_DEFAULT); $clob->save("some text"); OCICommit($conn); ?>

You can easily access stored procedures in the same way as you would from the commands line.
Esempio 2. Using Stored Procedures
<?php // by webmaster at remoterealty dot com $sth = OCIParse($dbh, "begin sp_newaddress( :address_id, '$firstname', '$lastname', '$company', '$address1', '$address2', '$city', '$state', '$postalcode', '$country', :error_code );end;"); // Questo codice richiama la stored procedure sp_newaddress, dove :address_id è // una variabile in/out e :error_code è una variabile out. // Quindi si effettua il binding: OCIBindByName($sth, ":address_id", $addr_id, 10); OCIBindByName($sth, ":error_code", $errorcode, 10); OCIExecute($sth); ?>

Sommario
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 di 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 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 temporary large object
OCI-Lob->writeToFile -- Alias di oci_lob_export()
oci_bind_by_name -- Lega una variabile PHP ad un segnaposto Oracle
oci_cancel -- Interrompe la lettura del cursore
oci_close -- Closes Oracle connection
oci_commit -- Commits outstanding statements
oci_connect -- Establishes a connection to the Oracle server
oci_define_by_name -- Uses a PHP variable for the define-step during a SELECT
oci_error -- Returns the last error found
oci_execute -- Executes a statement
oci_fetch_all -- Fetches all rows of result data into an array
oci_fetch_array -- Returns the next row from the result data as an associative or numeric array, or both
oci_fetch_assoc -- Returns the next row from the result data as an associative array
oci_fetch_object -- Returns the next row from the result data as an object
oci_fetch_row -- Returns the next row from the result data as a numeric array
oci_fetch -- Fetches the next row into result-buffer
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 -- Establishes a new connection to the Oracle server
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 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 outstanding transaction
oci_server_version -- Returns server version
oci_set_prefetch -- Sets number of rows to be prefetched
oci_statement_type -- Returns the type of an OCI statement
ocibindbyname -- Alias di oci_bind_by_name()
ocicancel -- Interrompe la lettura del cursore
ocicloselob -- Alias di OCI-Lob->close
ocicollappend -- Aggiunge un oggetto alla collezione
ocicollassign -- Assegna una collezione da un'altra collezione esistente
ocicollassignelem -- Assegna un elemento alla collezione in una specifica posizione
ocicollgetelem -- Coming soon
ocicollmax -- Coming soon
ocicollsize -- Coming soon
ocicolltrim -- Coming soon
ocicolumnisnull -- Verifica se un campo di risultato è NULL
ocicolumnname -- Restituisce il nome di un campo
ocicolumnprecision -- Coming soon
ocicolumnscale -- Coming soon
ocicolumnsize -- Restituisce la dimensione del campo
ocicolumntype -- Restituisce il tipo di dati di un campo
ocicolumntyperaw -- Coming soon
OCICommit -- Esegue le transazioni in sospeso
OCIDefineByName -- Utilizza una variabile PHP per la fase di definizione in un comando SELECT
OCIError -- Restituisce l'ultimo errore di stmt|conn|global
ociexecute -- Esegue un comando SQL
ocifetch -- Estrae la prossima tupla opnendola nel buffer di risultato.
ocifetchinto -- Estrae la prossima tupla ponendola in un array
ocifetchstatement -- Estrae tutte le tuple in un array
ocifreecollection -- Coming soon
ocifreecursor -- Libera tutte le risorse associate ad un cursore
ocifreedesc -- Cancella un descrittore di oggetto binario (LOB)
ocifreestatement -- Libera tutte le risorse associate ad un'istruzione
ociinternaldebug -- Abilita o disabilita la visualizzazione del debug interno.
ociloadlob -- Coming soon
ocilogoff -- Disconnette da Oracle
ocilogon -- Stabilisce una connessione a Oracle
ocinewcollection -- Coming soon
ocinewcursor -- Restituisce un nuovo cursore (Statement-Handle)
ocinewdescriptor -- Inizializza un nuovo descrittore LOB/FILE vuoto
ocinlogon -- Stabilisce, una nuova connessione a Oracle.
ocinumcols -- Restituisce il numero di campi che risultano da un comando SQL
ociparse -- Analizza una query e restituisce un'istruzione.
ociplogon -- Stabilisce una connessione permanente a Oracle.
ociresult -- Restituisce il valore di campo della tupla estratta
ocirollback -- Annulla le transazioni in sospeso
ocirowcount -- Restituisce il numero di tuple modificate
ocisavelob -- Coming soon
ocisavelobfile -- Coming soon
ociserverversion -- Restituisce una stringa contenente informazioni sulla versione del server
ocisetprefetch -- Imposta il numero di tuple da precaricare
ocistatementtype -- Restituisce il tipo di un'istruzione OCI
ociwritelobtofile -- Coming soon
ociwritetemporarylob -- Alias di OCI-Lob->writeTemporary

OCI-Collection->append

(no version information, might be only in CVS)

OCI-Collection->append -- Appends element to the collection

Descrizione

class OCI-Collection {

bool append ( mixed value )

}

Appends element to the end of the collection. Parameter value can be a string or a number.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Elenco dei parametri

value: The value to be added to the collection.

Vedere anche:

OCI-Collection->assign

(no version information, might be only in CVS)

OCI-Collection->assign -- Assigns a value to the collection from another existing collection

Descrizione

class OCI-Collection {

bool assign ( OCI-Collection 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.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Elenco dei parametri

from: An instance of OCI-Collection.

Vedere anche:

OCI-Collection->append

OCI-Collection->assignElem

(no version information, might be only in CVS)

OCI-Collection->assignElem -- Assigns a value to the element of the collection

Descrizione

class OCI-Collection {

bool assignElem ( int index, mixed value )

}

Assigns a value to the element with index index. Parameter value can be a string or a number.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Elenco dei parametri

index
value

Vedere anche:

OCI-Collection->getElem

OCI-Collection->free

(no version information, might be only in CVS)

OCI-Collection->free -- Frees the resources associated with the collection object

Descrizione

class OCI-Collection {

bool free ( void )

}

Frees the resources associated with the collection object.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

oci_new_collection

OCI-Collection->getElem

(no version information, might be only in CVS)

OCI-Collection->getElem -- Returns value of the element

Descrizione

class OCI-Collection {

mixed getElem ( int index )

}

Returns element's value with the index index (1-based).

OCI-Collection->getElem() 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.

Elenco dei parametri

index

Vedere anche:

OCI-Collection->assignElem

OCI-Collection->max

(no version information, might be only in CVS)

OCI-Collection->max -- Returns the maximum number of elements in the collection

Descrizione

class OCI-Collection {

int max ( void )

}

Returns the maximum number of elements in the collection. If the returned value is 0, then the number of elements is not limited. OCI-Collection->max() returns FALSE in case of error.

Vedere anche:

OCI-Collection->size

(no version information, might be only in CVS)

OCI-Collection->size -- Returns size of the collection

Descrizione

class OCI-Collection {

int size ( void )

}

Returns the number of elements in the collection or FALSE on error.

Vedere anche:

OCI-Collection->max

OCI-Collection->trim

(no version information, might be only in CVS)

OCI-Collection->trim -- Trims elements from the end of the collection

Descrizione

class OCI-Collection {

bool trim ( int num )

}

Trims num of elements from the end of the collection.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Elenco dei parametri

num

Vedere anche:

OCI-Collection->size

OCI-Lob->append

(no version information, might be only in CVS)

OCI-Lob->append -- Appends data from the large object to another large object

Descrizione

class OCI-Lob {

bool append ( OCI-Lob lob_from )

}

Appends data from the large object to the end of another large object.

Writing to the large object with OCI-Lob->append() 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.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Elenco dei parametri

lob_from

Vedere anche:

OCI-Lob->flush

OCI-Lob->setBuffering

OCI-Lob->getBuffering

OCI-Lob->close

(no version information, might be only in CVS)

OCI-Lob->close -- Closes LOB descriptor

Descrizione

class OCI-Lob {

bool close ( void )

}

OCI-Lob->close() closes descriptor of LOB or FILE. This function should be used only with OCI-Lob->writeTemporary.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

OCI-Lob->writeTemporary

OCI-Lob->eof

(no version information, might be only in CVS)

OCI-Lob->eof -- Tests for end-of-file on a large object's descriptor

Descrizione

class OCI-Lob {

bool eof ( void )

}

Returns TRUE if internal pointer of large object is at the end of LOB. Otherwise returns FALSE.

Vedere anche:

OCI-Lob->size

OCI-Lob->erase

(no version information, might be only in CVS)

OCI-Lob->erase -- Erases a specified portion of the internal LOB data

Descrizione

class OCI-Lob {

int erase ( [int offset [, int length]] )

}

Erases a specified portion of the internal LOB data starting at a specified offset. Parameters length and offset are optional. OCI-Lob->erase() erases all LOB data by default.

For BLOBs, erasing means that the existing LOB value is overwritten with zero-bytes. For CLOBs, the existing LOB value is overwritten with spaces.

OCI-Lob->erase() returns the actual number of characters/bytes erased or FALSE in case of error.

Elenco dei parametri

offset
length

Vedere anche:

OCI-Lob->truncate

OCI-Lob->export

(no version information, might be only in CVS)

OCI-Lob->export -- Exports LOB's contents to a file

Descrizione

class OCI-Lob {

bool export ( string filename [, int start [, int length]] )

}

Exports LOB contents to a file. The file name is given in the parameter filename. The optional parameter start indicates from where to start exporting and the parameter length - indicates the length of data to be exported.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Elenco dei parametri

filename
start
length

Vedere anche:

OCI-Lob->import

OCI-Lob->flush

(no version information, might be only in CVS)

OCI-Lob->flush -- Flushes/writes buffer of the LOB to the server

Descrizione

class OCI-Lob {

bool flush ( [int flag] )

}

OCI-Lob->flush() actually writes data to the server. By default, resources are not freed, but using flag OCI_LOB_BUFFER_FREE you 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 use OCI_LOB_BUFFER_FREE flag only when you are not going to work with the LOB anymore.

OCI-Lob->flush() returns FALSE if buffering was not enabled or an error occurred.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Elenco dei parametri

flag

Vedere anche:

OCI-Lob->getBuffering

OCI-Lob->setBuffering

OCI-Lob->free

(no version information, might be only in CVS)

OCI-Lob->free -- Frees resources associated with the LOB descriptor

Descrizione

class OCI-Lob {

bool free ( void )

}

Frees resources associated with the descriptor, previously allocated with oci_new_descriptor().

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

OCI-Lob->getBuffering

(no version information, might be only in CVS)

OCI-Lob->getBuffering -- Returns current state of buffering for the large object

Descrizione

class OCI-Lob {

bool getBuffering ( void )

}

Returns FALSE if buffering for the large object is off and TRUE if buffering is used.

Vedere anche:

OCI-Lob->setBuffering

OCI-Lob->import

(no version information, might be only in CVS)

OCI-Lob->import -- Imports file data to the LOB

Descrizione

class OCI-Lob {

bool import ( string filename )

}

Writes data from the filename in to the current position of large object.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Elenco dei parametri

filename

Vedere anche:

OCI-Lob->export

OCI-Lob->write

OCI-Lob->load

(no version information, might be only in CVS)

OCI-Lob->load -- Returns large object's contents

Descrizione

class OCI-Lob {

string load ( void )

}

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. In case of error OCI-Lob->load() returns FALSE.

Vedere anche:

OCI-Lob->read

(no version information, might be only in CVS)

OCI-Lob->read -- Reads part of the large object

Descrizione

class OCI-Lob {

string read ( int 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.

Returns FALSE in case of error.

Elenco dei parametri

length

Vedere anche:

OCI-Lob->load

OCI-Lob->write

OCI-Lob->rewind

(no version information, might be only in CVS)

OCI-Lob->rewind -- Moves the internal pointer to the beginning of the large object

Descrizione

class OCI-Lob {

bool rewind ( void )

}

Sets the internal pointer to the beginning of the large object.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

OCI-Lob->seek

OCI-Lob->tell

OCI-Lob->save

(no version information, might be only in CVS)

OCI-Lob->save -- Saves data to the large object

Descrizione

class OCI-Lob {

bool save ( string data [, int offset] )

}

Saves data to the large object. Parameter offset can be used to indicate offset from the beginning of the large object.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Elenco dei parametri

data

offset

Vedere anche:

OCI-Lob->write

OCI-Lob->import

OCI-Lob->saveFile

(no version information, might be only in CVS)

OCI-Lob->saveFile -- Alias di oci_lob_import()

Descrizione

This function is an alias of: oci_lob_import().

OCI-Lob->seek

(no version information, might be only in CVS)

OCI-Lob->seek -- Sets the internal pointer of the large object

Descrizione

class OCI-Lob {

bool seek ( int offset [, int whence] )

}

Sets the internal pointer of the large object. Parameter offset indicates the amount of bytes, on which internal pointer should be moved from the position, pointed by whence:

OCI_SEEK_SET - sets the position equal to offset

OCI_SEEK_CUR - adds offset bytes to the current position

OCI_SEEK_END - adds offset bytes to the end of large object (use negative value to move to a position before the end of large object)

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Elenco dei parametri

offset
whence

Vedere anche:

OCI-Lob->rewind

OCI-Lob->tell

OCI-Lob->eof

OCI-Lob->setBuffering

(no version information, might be only in CVS)

OCI-Lob->setBuffering -- Changes current state of buffering for the large object

Descrizione

class OCI-Lob {

bool setBuffering ( bool on_off )

}

lob->setBuffering() sets the buffering for the large object, depending on the value of the on_off parameter. Repeated calls to lob->setBuffering() with the same flag will return TRUE. The values for on_off are: TRUE for on and FALSE for off.

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.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Elenco dei parametri

on_off

Vedere anche:

OCI-Lob->getBuffering

OCI-Lob->size

(no version information, might be only in CVS)

OCI-Lob->size -- Returns size of large object

Descrizione

class OCI-Lob {

int size ( void )

}

Returns length of large object value or FALSE in case of error. Empty objects have zero length.

OCI-Lob->tell

(no version information, might be only in CVS)

OCI-Lob->tell -- Returns current position of internal pointer of large object

Descrizione

class OCI-Lob {

int tell ( void )

}

Returns current position of a LOB's internal pointer or FALSE if an error occurred.

Vedere anche:

OCI-Lob->rewind

OCI-Lob->size

OCI-Lob->eof

OCI-Lob->truncate

(no version information, might be only in CVS)

OCI-Lob->truncate -- Truncates large object

Descrizione

class OCI-Lob {

bool truncate ( [int length] )

}

If parameter length is given, OCI-Lob->truncate() truncates large object to length bytes. Otherwise, OCI-Lob->truncate() will purge the LOB completely.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Elenco dei parametri

length

Vedere anche:

OCI-Lob->erase

OCI-Lob->write

(no version information, might be only in CVS)

OCI-Lob->write -- Writes data to the large object

Descrizione

class OCI-Lob {

int write ( string data [, int length] )

}

Writes data from the parameter data into the current position of LOB's internal pointer. If the parameter length is given, writing will stop after length bytes have been written or the end of data is reached, whichever comes first.

OCI-Lob->write() returns the number of bytes written or FALSE in case of error.

Elenco dei parametri

data
length

Vedere anche:

OCI-Lob->read

OCI-Lob->writeTemporary

(no version information, might be only in CVS)

OCI-Lob->writeTemporary -- Writes temporary large object

Descrizione

class OCI-Lob {

bool writeTemporary ( string data [, int lob_type] )

}

Creates a temporary large object and writes data to it.

Parameter lob_type can be one of the following:

OCI_TEMP_BLOB is used to create temporary BLOBs

OCI_TEMP_CLOB is used to create temporary CLOBs

OCI-Lob->writeTemporary() creates a CLOB by default.

You should use OCI-Lob->close when the work with the object is over.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Elenco dei parametri

lob_type

Vedere anche:

OCI-Lob->close

OCI-Lob->writeToFile

(no version information, might be only in CVS)

OCI-Lob->writeToFile -- Alias di oci_lob_export()

Descrizione

This function is an alias of: oci_lob_export().

oci_bind_by_name

(PHP 5)

oci_bind_by_name -- Lega una variabile PHP ad un segnaposto Oracle

Descrizione

bool oci_bind_by_name ( resource stmt, string nome_ph, mixed &variabile [, int lungmax [, int tipo]] )

oci_bind_by_name() collega la variabile PHP variable al segnaposto Oracle ph_name. L'utilizzo in modalità input o output sarà determinato a run-time, e lo spazio di memoria necessario sarà allocato. Il parametro lungmax imposta la lunghezza massima del collegamento. Se si imposta lungmax a -1 oci_bind_by_name() userà l'attuale lunghezza di variabile per impostare la lunghezza massima.

Se si deve collegare un tipo dato astratto (LOB/ROWID/BFILE) occorre innanzitutto allocarlo usando la funzione oci_new_descriptor(). Il parametro lungmax non è usato con i tipi dati astratti e dovrebbe essere impostato a -1. La variabile tipo informa oracle sul tipo di descrittore che si vuole usare. I valori possibili sono:

OCI_B_FILE - per i BFILE;
OCI_B_CFILE - per i CFILE;
OCI_B_CLOB - per i CLOB;
OCI_B_BLOB - per i BLOB;
OCI_B_ROWID - per i ROWID;
OCI_B_NTY - per i named datatype;
OCI_B_CURSOR - per i cursori precedentemente creati con oci_new_cursor().

Esempio 1. esempio di ocibindbyname()
<?php /* esempio di oci_bind_by_name thies at thieso dot net (980221) inserisce 3 tuple in emp, e usa ROWID per aggiornare le tuple subito dopo l'inserimento. */ $conn = oci_connect("scott", "tiger"); $stmt = oci_parse($conn, " INSERT INTO emp (empno, ename) VALUES (:empno,:ename) RETURNING ROWID INTO :rid "); $data = array( 1111 => "Larry", 2222 => "Bill", 3333 => "Jim" ); $rowid = oci_new_descriptor($conn, OCI_D_ROWID); oci_bind_by_name($stmt, ":empno", $empno, 32); oci_bind_by_name($stmt, ":ename", $ename, 32); oci_bind_by_name($stmt, ":rid", $rowid, -1, OCI_B_ROWID); $update = oci_parse($conn, " UPDATE emp SET sal = :sal WHERE ROWID = :rid "); oci_bind_by_name($update, ":rid", $rowid, -1, OCI_B_ROWID); oci_bind_by_name($update, ":sal", $sal, 32); $sal = 10000; while (list($empno, $ename) = each($data)) { oci_execute($stmt); oci_execute($update); } $rowid->free(); oci_free_statement($update); oci_free_statement($stmt); $stmt = oci_parse($conn, " SELECT * FROM emp WHERE empno IN (1111,2222,3333) "); oci_execute($stmt); while ($row = oci_fetch_assoc($stmt)) { var_dump($row); } oci_free_statement($stmt); /* delete our "junk" from the emp table.... */ $stmt = oci_parse($conn, " DELETE FROM emp WHERE empno IN (1111,2222,3333) "); oci_execute($stmt); oci_free_statement($stmt); oci_close($conn); ?>

Ricordarsi che questa funzione elimina gli spazi alla fine della riga. Vedere il seguente esempio:

Esempio 2. esempio di oci_bind_by_name()
<?php $connection = oci_connect('apelsin','kanistra'); $query = "INSERT INTO test_table VALUES(:id, :text)"; $statement = oci_parse($query); oci_bind_by_name($statement, ":id", 1); oci_bind_by_name($statement, ":text", "Qui ci sono degli spazi "); oci_execute($statement); /* Questo codice inserisce nel DB la stringa 'Qui ci sono degli spazi', senza gli spazi finali */ ?>

Esempio 3. esempio di oci_bind_by_name()
<?php $connection = oci_connect('apelsin','kanistra'); $query = "INSERT INTO test_table VALUES(:id, 'Qui ci sono degli spazi ')"; $statement = oci_parse($query); oci_bind_by_name($statement, ":id", 1); oci_execute($statement); /* Questo codice aggiunge 'Qui ci sono degli spazi ', mantenendo gli spazi */ ?>

Avvertimento

Non utilizzare le magic_quotes_gpc o addslashes() e oci_bind_by_name() simultaneamente in quanto le virgolette non sono necessarie nelle variabili e qualsiasi virgoletta aggiunta automaticamente verrà scritta nel database dal momento che ocibindbyname() non è in grado di distinguere le virgolette aggiunte automaticamente da quelle intenzionali.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Nota: Nelle versioni di PHP antecedenti la 5.0.0 si deve usare ocibindbyname(). Questo nome può ancora essere utilizzato, è rimasto come alias di oci_bind_by_name() per mantenere la compatibilità. Ciò è comunque deprecato e non raccomandato.

oci_cancel

(PHP 5)

oci_cancel -- Interrompe la lettura del cursore

Descrizione

bool oci_cancel ( resource stmt )

oci_cancel() invalida un cursore, rilasciando tutte le risorse associate e cancella la possibilità di leggere da esso.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Nelle versioni di PHP antecedenti la 5.0.0 si deve usare ocicancel(). Questo nome può ancora essere utilizzato, è rimasto come alias di oci_cancel() per mantenere la compatibilità. Ciò è comunque deprecato e non raccomandato.

oci_close

(PHP 5)

oci_close -- Closes Oracle connection

Description

bool oci_close ( resource connection )

oci_close() closes the Oracle connection connection.

Nota: Starting from the version 1.1 oci_close() correctly closes the Oracle connection. Use oci8.old_oci_close_semantics option to restore old behaviour of this function.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Nota: In PHP versions before 5.0.0 you must use ocilogoff() instead. This name still can be used, it was left as alias of oci_close() for downwards compatability. This, however, is deprecated and not recommended.

oci_commit

(PHP 5)

oci_commit -- Commits outstanding statements

Description

bool oci_commit ( resource connection )

oci_commit() commits all outstanding statements for the active transaction on the Oracle connection connection.

Esempio 1. oci_commit() example
<?php // Login to Oracle server $conn = oci_connect('scott', 'tiger'); // Parse SQL $stmt = oci_parse($conn, " INSERT INTO employees (name, surname) VALUES ('Maxim', 'Maletsky') "); /* Execute statement OCI_DEFAULT tells oci_execute() not to commit statement immediately */ oci_execute($stmt, OCI_DEFAULT); /* .... Parsing and executing other statements here ... .... */ // Commit transaction $committed = oci_commit($conn); // Test whether commit was successful. If error occurred, return error message if (!$committed) { $error = oci_error($conn); echo 'Commit failed. Oracle reports: ' . $error['message']; } ?>

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Nota: 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, or oci_rollback() to abort it.

Nota: In PHP versions before 5.0.0 you must use ocicommit() instead. This name still can be used, it was left as alias of oci_commit() for downwards compatability. This, however, is deprecated and not recommended.

oci_connect

(PHP 5)

oci_connect -- Establishes a connection to the Oracle server

Description

resource oci_connect ( string username, string password [, string db [, string charset [, int session_mode]]] )

oci_connect() returns a connection identifier needed for most other OCI calls. The optional third parameter can either contain the name of the local Oracle instance or the name of the entry in tnsnames.ora to which you want to connect. If the optional third parameter is not specified, PHP uses the environment variables ORACLE_SID (Oracle instance) or TWO_TASK (tnsnames.ora) to determine which database to connect to.

Parameter session_mode is available since version 1.1 and accepts the following values: OCI_DEFAULT, OCI_SYSOPER and OCI_SYSDBA. If either OCI_SYSOPER or OCI_SYSDBA were specified, oci_connect() 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.

Nota: If you're using PHP with Oracle Instant Client, you can use easy connect naming method described here: http://download-west.oracle.com/docs/cd/B12037_01/network.101/b10775/naming.htm#i498306. Basically this means you can specify "//db_host[:port]/database_name" as database name. But if you want to use the old way of naming you must set either ORACLE_HOME or TNS_ADMIN.

Nota: 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 queries issued against one handle are also applied to the other handles, because they are the same handle. This behaviour is demonstrated in Example 1 below. If you require two handles to be transactionally isolated from each other, you should use oci_new_connect() instead.

Using Oracle server version 9.2 and greater, you can indicate charset parameter, which will be used in the new connection. If you're using Oracle server < 9.2, this parameter will be ignored and NLS_LANG environment variable will be used instead.

Esempio 1. oci_connect() example
<?php echo "<pre>"; $db = ""; $c1 = oci_connect("scott", "tiger", $db); $c2 = oci_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); // Insert a row using c1 insert_data($c2); // Insert a row using c2 select_data($c1); // Results of both inserts are returned select_data($c2); rollback($c1); // Rollback using c1 select_data($c1); // Both inserts have been rolled back select_data($c2); insert_data($c2); // Insert a row using c2 commit($c2); // Commit using c2 select_data($c1); // Result of c2 insert is returned delete_data($c1); // Delete all rows in table using c1 select_data($c1); // No rows returned select_data($c2); // No rows returned commit($c1); // Commit using c1 select_data($c1); // No rows returned select_data($c2); // No rows returned drop_table($c1); echo "</pre>"; ?>

oci_connect() returns FALSE if an error occured.

Nota: In PHP versions before 5.0.0 you must use ocilogon() instead. This name still can be used, it was left as the alias of oci_connect() for downwards compatability. This, however, is deprecated and not recommended.

oci_define_by_name

(PHP 5)

oci_define_by_name -- Uses a PHP variable for the define-step during a SELECT

Description

bool oci_define_by_name ( resource statement, string column_name, mixed &variable [, int type] )

oci_define_by_name() defines PHP variables for fetches of SQL-Columns. Take into consideration that Oracle uses ALL-UPPERCASE column names, whereby in your select you can also use lowercase. oci_define_by_name() expects the column_name to be in uppercase. If you define a variable that doesn't exists in your select statement, no error will be issued.

If you need to define an abstract datatype (LOB/ROWID/BFILE) you must allocate it first using oci_new_descriptor(). See also the oci_bind_by_name() function.

Esempio 1. oci_define_by_name() example

<?php
/* oci_define_by_name example - thies at thieso dot net (980219) */

$conn = oci_connect("scott", "tiger");

$stmt = oci_parse($conn, "SELECT empno, ename FROM emp");

/* the define MUST be done BEFORE oci_execute! */

oci_define_by_name($stmt, "EMPNO", $empno);
oci_define_by_name($stmt, "ENAME", $ename);

oci_execute($stmt);

while (oci_fetch($stmt)) {
    echo "empno:" . $empno . "\n";
    echo "ename:" . $ename . "\n";
}

oci_free_statement($stmt);
oci_close($conn);
?>

Nota: In PHP versions before 5.0.0 you must use ocidefinebyname() instead. This name still can be used, it was left as alias of oci_define_by_name() for downwards compatability. This, however, is deprecated and not recommended.

oci_error

(PHP 5)

oci_error -- Returns the last error found

Description

array oci_error ( [resource source] )

For most errors, the parameter is the most appropriate resource handle. For connection errors with oci_connect(), oci_new_connect() or oci_pconnect(), do not pass a parameter. If no error is found, oci_error() returns FALSE. oci_error() returns the error as an associative array. In this array, code consists the oracle error code and message the oracle error string.

As of PHP 4.3: offset and sqltext will also be included in the return array to indicate the location of the error and the original SQL text which caused it.

Esempio 1. Displaying the Oracle error message after a connection error
$conn = @oci_connect("scott", "tiger", "mydb"); if (!$conn) { $e = oci_error(); // For oci_connect errors pass no handle echo htmlentities($e['message']); }

Esempio 2. Displaying the Oracle error message after a parsing error
$stmt = @oci_parse($conn, "select ' from dual"); // note mismatched quote if (!$stmt) { $e = oci_error($conn); // For oci_parse errors pass the connection handle echo htmlentities($e['message']); }

Esempio 3. Displaying the Oracle error message and problematic statement after an execution error
$r = oci_execute($stmt); if (!$r) { $e = oci_error($stmt); // For oci_execute errors pass the statementhandle echo htmlentities($e['message']); echo "<pre>"; echo htmlentities($e['sqltext']); printf("\n%".($e['offset']+1)."s", "^"); echo "</pre>"; }

Nota: In PHP versions before 5.0.0 you must use ocierror() instead. This name still can be used, it was left as alias of oci_error() for downwards compatability. This, however, is deprecated and not recommended.

oci_execute

(PHP 5)

oci_execute -- Executes a statement

Description

bool oci_execute ( resource stmt [, int mode] )

oci_execute() executes a previously parsed statement (see oci_parse()). The optional mode allows you to specify the execution mode (default is OCI_COMMIT_ON_SUCCESS). If you don't want statements to be committed automatically, you should specify OCI_DEFAULT as your mode.

When using OCI_DEFAULT mode, you're creating a transaction. 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, or oci_rollback() to abort it.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Nota: In PHP versions before 5.0.0 you must use ociexecute() instead. This name still can be used, it was left as alias of oci_execute() for downwards compatability. This, however, is deprecated and not recommended.

oci_fetch_all

(PHP 5)

oci_fetch_all -- Fetches all rows of result data into an array

Description

int oci_fetch_all ( resource statement, array &output [, int skip [, int maxrows [, int flags]]] )

oci_fetch_all() fetches all the rows from a result into a user-defined array. oci_fetch_all() returns the number of rows fetched or FALSE in case of an error. skip is the number of initial rows to ignore when fetching the result (default value of 0, to start at the first line). maxrows is the number of rows to read, starting at the skipth row (default to -1, meaning all the rows).

Nota: This function sets NULL fields to PHP NULL value.

Parameter flags can be any combination of the following:

OCI_FETCHSTATEMENT_BY_ROW

OCI_FETCHSTATEMENT_BY_COLUMN (default value)

OCI_NUM

OCI_ASSOC

Esempio 1. oci_fetch_all() example
<?php /* oci_fetch_all example mbritton at verinet dot com (990624) */ $conn = oci_connect("scott", "tiger"); $stmt = oci_parse($conn, "select * from emp"); oci_execute($stmt); $nrows = oci_fetch_all($stmt, $results); if ($nrows > 0) { echo "<table border=\"1\">\n"; echo "<tr>\n"; foreach ($results as $key => $val) { echo "<th>$key</th>\n"; } echo "</tr>\n"; for ($i = 0; $i < $nrows; $i++) { echo "<tr>\n"; foreach ($results as $data) { echo "<td>$data[$i]</td>\n"; } echo "</tr>\n"; } echo "</table>\n"; } else { echo "No data found<br />\n"; } echo "$nrows Records Selected<br />\n"; oci_free_statement($stmt); oci_close($conn); ?>

For details on the data type mapping performed by the oci8 driver, see the datatypes supported by the driver

oci_fetch_all() returns FALSE in case of error.

Nota: In PHP versions before 5.0.0 you must use ocifetchstatement() instead. This name still can be used, it was left as alias of oci_fetch_all() for downwards compatability. This, however, is deprecated and not recommended.

oci_fetch_array

(PHP 5)

oci_fetch_array -- Returns the next row from the result data as an associative or numeric array, or both

Description

array oci_fetch_array ( resource statement [, int mode] )

Returns an array, which corresponds to the next result row or FALSE in case of error or there are no more rows in the result.

oci_fetch_array() returns an array with both associative and numeric indices.

Nota: This function sets NULL fields to PHP NULL value.

An optional second parameter can be any combination of the following constants:

OCI_BOTH - return an array with both associative and numeric indices (the same as OCI_ASSOC + OCI_NUM). This is the default behavior.

OCI_ASSOC - return an associative array (as oci_fetch_assoc() works).

OCI_NUM - return a numeric array, (as oci_fetch_row() works).

OCI_RETURN_NULLS - create empty elements for the NULL fields.

OCI_RETURN_LOBS - return the value of a LOB of the descriptor.

Default mode is OCI_BOTH.

It should be mentioned here, that oci_fetch_array() is insignificantly slower, than oci_fetch_row(), but much more handy.

Nota: Oracle returns all field names in uppercase and associative indices in the result array will be uppercased too.

Esempio 1. oci_fetch_array() with OCI_BOTH example
<?php $connection = oci_connect("apelsin", "kanistra"); $query = "SELECT id, name FROM fruits"; $statement = oci_parse ($connection, $query); oci_execute ($statement); while ($row = oci_fetch_array ($statement, OCI_BOTH)) { echo $row[0]." and ".$row['ID']." is the same<br>"; echo $row[1]." and ".$row['NAME']." is the same<br>"; } ?>

Esempio 2. oci_fetch_array() with OCI_NUM example
<?php $connection = oci_connect("user", "password"); $query = "SELECT id, name, lob_field FROM fruits"; $statement = oci_parse ($connection, $query); oci_execute ($statement); while ($row = oci_fetch_array ($statement, OCI_NUM)) { echo $row[0]."<br>"; echo $row[1]."<br>"; echo $row[2]->read(100)."<br>"; //this will output first 100 bytes from LOB } ?>

Esempio 3. oci_fetch_array() with OCI_ASSOC example
<?php $connection = oci_connect("user", "password"); $query = "SELECT id, name, lob_field FROM fruits"; $statement = oci_parse ($connection, $query); oci_execute ($statement); while ($row = oci_fetch_array ($statement, OCI_NUM)) { echo $row['ID']."<br>"; echo $row['NAME']."<br>"; echo $row['LOB_FIELD']."<br>"; //this will output "Object id #1" } ?>

Esempio 4. oci_fetch_array() with OCI_RETURN_LOBS example
<?php $connection = oci_connect("user", "password"); $query = "SELECT id, name, lob_field FROM fruits"; $statement = oci_parse ($connection, $query); oci_execute ($statement); while ($row = oci_fetch_array ($statement, OCI_NUM)) { echo $row[0]."<br>"; echo $row[1]."<br>"; echo $row['LOB_FIELD']."<br>"; //this will output LOB's content } ?>

For details on the data type mapping performed by the oci8 driver, see the datatypes supported by the driver

oci_fetch_assoc

(PHP 5)

oci_fetch_assoc -- Returns the next row from the result data as an associative array

Description

array oci_fetch_assoc ( resource statement )

oci_fetch_assoc() returns the next row from the result data as an associative array (identical to oci_fetch_array() call with OCI_ASSOC flag).

Nota: This function sets NULL fields to PHP NULL value.

A subsequent call to oci_fetch_assoc() will return the next row or FALSE if there are no more rows.

Nota: Oracle returns all field names in uppercase and associative indices in the result array will be uppercased too.

For details on the data type mapping performed by the oci8 driver, see the datatypes supported by the driver

oci_fetch_object

(PHP 5)

oci_fetch_object -- Returns the next row from the result data as an object

Description

object oci_fetch_object ( resource statement )

oci_fetch_object() returns the next row from the result data as an object, which attributes correspond to fields in statement.

Nota: This function sets NULL fields to PHP NULL value.

Subsequent calls to oci_fetch_object() will return the next row from the result or FALSE if there are no more rows.

Nota: Oracle returns all field names in uppercase and attributes' names in the result object will be in uppercase as well.

For details on the data type mapping performed by the oci8 driver, see the datatypes supported by the driver

oci_fetch_row

(PHP 5)

oci_fetch_row -- Returns the next row from the result data as a numeric array

Description

array oci_fetch_row ( resource statement )

Calling oci_fetch_row() is identical to oci_fetch_array() with OCI_NUM flag and returns the next row from the result data as a numeric array.

Nota: This function sets NULL fields to PHP NULL value.

Subsequent calls to oci_fetch_row() will return the next row from the result data or FALSE if there are no more rows.

For details on the data type mapping performed by the oci8 driver, see the datatypes supported by the driver

oci_fetch

(PHP 5)

oci_fetch -- Fetches the next row into result-buffer

Description

bool oci_fetch ( resource statement )

oci_fetch() fetches the next row (for SELECT statements) into the internal result-buffer.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

For details on the data type mapping performed by the oci8 driver, see the datatypes supported by the driver

Nota: In PHP versions before 5.0.0 you must use ocifetch() instead. This name still can be used, it was left as alias of oci_fetch() for downwards compatability. This, however, is deprecated and not recommended.

oci_field_is_null

(PHP 5)

oci_field_is_null -- Checks if the field is NULL

Description

bool oci_field_is_null ( resource stmt, mixed field )

oci_field_is_null() returns TRUE if field field from the statement is NULL. Parameter field could be a field's index or a field's name (uppercased).

Nota: 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)

oci_field_name -- Returns the name of a field from the statement

Description

string oci_field_name ( resource statement, int field )

oci_field_name() returns the name of the field corresponding to the field number (1-based).

Esempio 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); ?>

Nota: 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.

oci_field_precision

(PHP 5)

oci_field_precision -- Tell the precision of a field

Description

int oci_field_precision ( resource statement, int field )

Returns precision of the field with field index (1-based).

For FLOAT columns, precision is nonzero and scale is -127. If precision is 0, then column is NUMBER. Else it's NUMBER(precision, scale).

Nota: 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.

oci_field_scale

(PHP 5)

oci_field_scale -- Tell the scale of the field

Description

int oci_field_scale ( resource statement, int field )

Returns scale of the column with field index (1-based) or FALSE if there is no such 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).

Nota: 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.

oci_field_size

(PHP 5)

oci_field_size -- Returns field's size

Description

int oci_field_size ( resource stmt, mixed field )

oci_field_size() returns the size of a field in bytes. Value of field parameter can be the field's index (1-based) or it's name.

Esempio 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); ?>

Nota: 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.

oci_field_type_raw

(PHP 5)

oci_field_type_raw -- Tell the raw Oracle data type of the field

Description

int oci_field_type_raw ( resource statement, int field )

oci_field_type_raw() returns Oracle's raw data type of the field.

Nota: 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.

However, if you want to get field's type, then oci_field_type() will suit you better. See oci_field_type() for additional information.

oci_field_type

(PHP 5)

oci_field_type -- Returns field's data type

Description

mixed oci_field_type ( resource stmt, int field )

oci_field_type() returns a field's data type. Parameter field is an index of the field in the statement (1-based).

Esempio 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); ?>

Nota: 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.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

oci_lob_is_equal

(PHP 5)

oci_lob_is_equal -- Compares two LOB/FILE locators for equality

Description

bool oci_lob_is_equal ( OCI-Lob lob1, OCI-Lob lob2 )

Compares two LOB/FILE locators. Returns TRUE if these objects are equal and FALSE otherwise.

oci_new_collection

(PHP 5)

oci_new_collection -- Allocates new collection object

Description

OCI-Collection oci_new_collection ( resource connection, string tdo [, string schema] )

Allocates a new collection object. Parameter tdo should be a valid named type (uppercase). The third, optional parameter schema should point to the scheme, where the named type was created. oci_new_collection() uses the name of the current user as the default value of schema.

oci_new_collection() returns FALSE on error.

Nota: 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)

oci_new_connect -- Establishes a new connection to the Oracle server

Description

resource oci_new_connect ( string username, string password [, string db [, string charset [, int session_mode]]] )

oci_new_connect() 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.

The optional third parameter can either contain the name of the local Oracle instance or the name of the entry in tnsnames.ora. If the third parameter is not specified, PHP uses environment variables ORACLE_SID and TWO_TASK to determine the name of local Oracle instance and location of tnsnames.ora accordingly.

Parameter session_mode is available since version 1.1 and accepts the following values: OCI_DEFAULT, OCI_SYSOPER and OCI_SYSDBA. If either OCI_SYSOPER or OCI_SYSDBA were specified, oci_new_connect() 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.

Nota: If you're using PHP with Oracle Instant Client, you can use easy connect naming method described here: http://download-west.oracle.com/docs/cd/B12037_01/network.101/b10775/naming.htm#i498306. Basically this means you can specify "//db_host[:port]/database_name" as database name. But if you want to use the old way of naming you must set either ORACLE_HOME or TNS_ADMIN.

The following demonstrates how you can separate connections.
Esempio 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>"; ?>

oci_new_connect() returns FALSE on error.

Nota: In PHP versions before 5.0.0 you must use ocinlogon() instead. This name still can be used, it was left as alias of oci_new_connect() for downwards compatability. This, however, is deprecated and not recommended.

oci_new_cursor

(PHP 5)

oci_new_cursor -- Allocates and returns a new cursor (statement handle)

Description

resource oci_new_cursor ( resource connection )

oci_new_cursor() allocates a new statement handle on the specified connection.

Esempio 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); ?>

Esempio 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); ?>

oci_new_cursor() returns FALSE on error.

Nota: 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)

oci_new_descriptor -- Initializes a new empty LOB or FILE descriptor

Description

OCI-Lob oci_new_descriptor ( resource connection [, int type] )

oci_new_descriptor() allocates resources to hold descriptor or LOB locator. Valid values for type are: OCI_D_FILE, OCI_D_LOB and OCI_D_ROWID.

Esempio 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); } ?>

Esempio 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); ?>

oci_new_descriptor() returns FALSE on error.

Nota: 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)

oci_num_fields -- Returns the number of result columns in a statement

Description

int oci_num_fields ( resource statement )

oci_num_fields() returns the number of columns in the statement.

Esempio 1. oci_num_fields() example
<?php echo "<pre>\n"; $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); echo "</pre>"; ?>

oci_num_fields() returns FALSE on error.

Nota: 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)

oci_num_rows -- Returns number of rows affected during statement execution

Description

int oci_num_rows ( resource stmt )

oci_num_rows() returns number of rows affected during statement execution.

Nota: 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.

Esempio 1. oci_num_rows() example
<?php echo "<pre>"; $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); echo "</pre>"; ?>

oci_num_rows() returns FALSE on error.

Nota: 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)

oci_parse -- Prepares Oracle statement for execution

Description

resource oci_parse ( resource connection, string query )

oci_parse() prepares the query using connection and returns the statement identifier, which can be used with oci_bind_by_name(), oci_execute() and other functions.

Nota: This function does not validate query. The only way to find out if query is valid SQL or PL/SQL statement - is to execute it.

oci_parse() returns FALSE on error.

Nota: In PHP versions before 5.0.0 you must use ociparse() instead. This name still can be used, it was left as alias of oci_parse() for downwards compatability. This, however, is deprecated and not recommended.

oci_password_change

(PHP 5)

oci_password_change -- Changes password of Oracle's user

Description

bool oci_password_change ( resource connection, string username, string old_password, string new_password )

resource oci_password_change ( string dbname, string username, string old_password, string new_password )

Changes password for user with username. Parameters old_password and new_password should indicate old and new passwords respectively.

Nota: The second oci_password_change() syntax is available since version 1.1.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Nota: 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)

oci_pconnect -- Connect to an Oracle database using a persistent connection

Description

resource oci_pconnect ( string username, string password [, string db [, string charset [, int session_mode]]] )

oci_pconnect() 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.

Nota: Starting with version 1.1 of the oci8 extension, the lifetime and maximum amount of persistent Oracle connections can be tuned by setting the following configuration values: oci8.persistent_timeout, oci8.ping_interval and oci8.max_persistent.

Nota: If you're using PHP with Oracle Instant Client, you can use easy connect naming method described here: http://download-west.oracle.com/docs/cd/B12037_01/network.101/b10775/naming.htm#i498306. Basically this means you can specify "//db_host[:port]/database_name" as database name. But if you want to use the old way of naming you must set either ORACLE_HOME or TNS_ADMIN.

oci_pconnect() returns connection identifier or FALSE on error.

Nota: In PHP versions before 5.0.0 you must use ociplogon() instead. This name still can be used, it was left as alias of oci_pconnect() for downwards compatability. This, however, is deprecated and not recommended.

oci_result

(PHP 5)

oci_result -- Returns field's value from the fetched row

Description

mixed oci_result ( resource statement, mixed field )

oci_result() returns the data from the field field in the current row, fetched by oci_fetch(). oci_result() returns everything as strings except for abstract types (ROWIDs, LOBs and FILEs). oci_result() returns FALSE on error.

You can either use the column number (1-based) or the column name (in uppercase) for the field() parameter.

Nota: 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.

For details on the data type mapping performed by the oci8 driver, see the datatypes supported by the driver

oci_rollback

(PHP 5)

oci_rollback -- Rolls back outstanding transaction

Description

bool oci_rollback ( resource connection )

oci_rollback() rolls back all outstanding statements for Oracle connection connection.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Nota: 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, or oci_rollback() to abort it.

Nota: In PHP versions before 5.0.0 you must use ocirollback() instead. This name still can be used, it was left as alias of oci_rollback() for downwards compatability. This, however, is deprecated and not recommended.

oci_server_version

(PHP 5)

oci_server_version -- Returns server version

Description

string oci_server_version ( resource connection )

Returns a string with version information of the Oracle server, which uses connection connection or returns FALSE on error.

Esempio 1. oci_server_version() example
<?php $conn = oci_connect("scott", "tiger"); echo "Server Version: " . oci_server_version($conn); oci_close($conn); ?>

Nota: In PHP versions before 5.0.0 you must use ociserverversion() instead. This name still can be used, it was left as alias of oci_server_version() for downwards compatability. This, however, is deprecated and not recommended.

oci_set_prefetch

(PHP 5)

oci_set_prefetch -- Sets number of rows to be prefetched

Description

bool oci_set_prefetch ( resource statement [, int rows] )

Sets the number of rows to be prefetched after successful call to oci_execute(). The default value for rows is 1.

Nota: In PHP versions before 5.0.0 you must use ocisetprefetch() instead. This name still can be used, it was left as alias of oci_set_prefetch() for downwards compatability. This, however, is deprecated and not recommended.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

See also oci8_.default_prefetch ini option.

oci_statement_type

(PHP 5)

oci_statement_type -- Returns the type of an OCI statement

Description

string oci_statement_type ( resource statement )

oci_statement_type() returns the query type of statement statement as one of the following values:

SELECT
UPDATE
DELETE
INSERT
CREATE
DROP
ALTER
BEGIN
DECLARE
UNKNOWN

Parameter statement is a valid OCI statement identifier, returned from oci_parse().

Esempio 1. oci_statement_type() example
<?php $conn = oci_connect("scott", "tiger"); $sql = "delete from emp where deptno = 10"; $stmt = oci_parse($conn, $sql); if (oci_statement_type($stmt) == "DELETE") { die("You are not allowed to delete from this table<br />"); } oci_close($conn); ?>

oci_statement_type() returns FALSE on error.

Nota: In PHP versions before 5.0.0 you must use ocistatementtype() instead. This name still can be used, it was left as alias of oci_statement_type() for downwards compatability. This, however, is deprecated and not recommended.

ocibindbyname

(PHP 3 >= 3.0.4, PHP 4, PHP 5)

ocibindbyname -- Alias di oci_bind_by_name()

Descrizione

This function is an alias of: oci_bind_by_name().

ocicancel

(PHP 3 >= 3.0.8, PHP 4, PHP 5)

ocicancel -- Interrompe la lettura del cursore

Descrizione

bool ocicancel ( resource stmt )

Se non si vogliono leggere altri dati da un cursore, chiamare ocicancel().

ocicloselob

(no version information, might be only in CVS)

bool ocicolumnisnull ( resource stmt, mixed col )

ocicolumnisnull() restituisce TRUE se il campo col nel risultato dell'istruzione stmt è NULL. Si può usare il numero del campo (primo campo=1) o il nome del campo per il parametro col.

ocicolumnname

(PHP 3 >= 3.0.4, PHP 4, PHP 5)

ocicolumnname -- Restituisce il nome di un campo

Descrizione

string ocicolumnname ( int stmt, int col )

int ocicolumnsize ( int stmt, mixed column )

ocicolumnsize() restituisce la dimensione del campo come riportata da Oracle. Si può usare il numero del campo (primo campo=1) o il nome del campo per il parametro col.

Esempio 1. esempio di ocicolumnsize()
<?php print "<HTML><PRE>\n"; $conn = OCILogon("scott", "tiger"); $stmt = OCIParse($conn,"select * from emp"); OCIExecute($stmt); print "<TABLE BORDER=\"1\">"; print "<TR>"; print "<TH>Name</TH>"; print "<TH>Type</TH>"; print "<TH>Length</TH>"; print "</TR>"; $ncols = OCINumCols($stmt); for ( $i = 1; $i <= $ncols; $i++ ) { $column_name = OCIColumnName($stmt,$i); $column_type = OCIColumnType($stmt,$i); $column_size = OCIColumnSize($stmt,$i); print "<TR>"; print "<TD>$column_name</TD>"; print "<TD>$column_type</TD>"; print "<TD>$column_size</TD>"; print "</TR>"; } print "</TABLE>"; OCIFreeStatement($stmt); OCILogoff($conn); print "</PRE>"; print "</HTML>\n"; ?>

Vedere anche ocinumcols(), ocicolumnname() e ocicolumnsize().

ocicolumntype

(PHP 3 >= 3.0.4, PHP 4, PHP 5)

ocicolumntype -- Restituisce il tipo di dati di un campo

Descrizione

mixed ocicolumntype ( int stmt, int col )

ocicolumntype() restituisce il tipo del campo corrispondente alla posizione (1 = primo campo) specificata.

Esempio 1. OCIColumnType
<?php print "<HTML><PRE>\n"; $conn = OCILogon("scott", "tiger"); $stmt = OCIParse($conn,"select * from emp"); OCIExecute($stmt); print "<TABLE BORDER=\"1\">"; print "<TR>"; print "<TH>Name</TH>"; print "<TH>Type</TH>"; print "<TH>Length</TH>"; print "</TR>"; $ncols = OCINumCols($stmt); for ( $i = 1; $i <= $ncols; $i++ ) { $column_name = OCIColumnName($stmt,$i); $column_type = OCIColumnType($stmt,$i); $column_size = OCIColumnSize($stmt,$i); print "<TR>"; print "<TD>$column_name</TD>"; print "<TD>$column_type</TD>"; print "<TD>$column_size</TD>"; print "</TR>"; } print "</TABLE>\n"; OCIFreeStatement($stmt); OCILogoff($conn); print "</PRE>"; print "</HTML>\n"; ?>

Vedere anche ocinumcols(), ocicolumnname(), e ocicolumnsize().

ocicolumntyperaw

(PHP 4, PHP 5)

ocicolumntyperaw -- Coming soon

Descrizione

mixed ocicolumntyperaw ( int stmt, int col )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

OCICommit

(PHP 3 >= 3.0.7, PHP 4, PHP 5)

OCICommit -- Esegue le transazioni in sospeso

Descrizione

bool OCICommit ( int connection )

ocicommit() esegue tutte le transazioni in sospeso sulla connessione Oracle connection. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Questo esempio dimostra l'utilizzo di OCICommit.
Esempio 1. OCICommit
<?php // Login sul server Oracle $conn = OCILogon('scott', 'tiger'); // Parse SQL $stmt = OCIParse($conn, "INSERT INTO impiegati (nome, cognome) VALUES ('Massimo', 'Carlotti')"); // Esecuzione dello statement OCIExecute($stmt); // Commit della transazione $committed = OCICommit($conn); // Valuta se la commit ha funzionata. Se c'e' un errore, restituisce il messaggio di errore if(!$committed) { $error = OCIError($conn); echo 'Commit fallito. Oracle ha restituito: ' . $error['message']; } // Chiusura della connessione OCILogoff($conn); ?>

Vedere anche ocirollback().

OCIDefineByName

(PHP 3 >= 3.0.7, PHP 4, PHP 5)

OCIDefineByName -- Utilizza una variabile PHP per la fase di definizione in un comando SELECT

Descrizione

bool ocidefinebyname ( int stmt, string Column-Name, mixed variable [, int type] )

ocidefinebyname() aggancia le variabili PHP ai campi SQL. Attenzione: Oracle usa nomi di colonna MAIUSCOLI, mentre nella SELECT si possono anche scrivere minuscoli. ocidefinebyname() vuole il parametro Column-Name in caratteri maiuscoli. Se si definisce una variabile che non esiste nel comando SELECT, non viene dato alcun errore!

Se occorre definire un tipo di dati astratto (LOB/ROWID/BFILE) lo si deve prima allocare usando la funzione OCINewDescriptor(). Vedere anche la funzione OCIBindByName().

Esempio 1. OCIDefineByName

<?php
/* OCIDefineByName example - thies@thieso.net (980219) */

$conn = OCILogon("scott","tiger");

$stmt = OCIParse($conn,"select empno, ename from emp");

/* il define DEVE essere eseguito PRIMA di ociexecute! */

OCIDefineByName($stmt,"EMPNO",$empno);
OCIDefineByName($stmt,"ENAME",$ename);

OCIExecute($stmt);

while (OCIFetch($stmt)) {
    echo "empno:".$empno."\n";
    echo "ename:".$ename."\n";
}

OCIFreeStatement($stmt);
OCILogoff($conn);
?>

OCIError

(PHP 3 >= 3.0.7, PHP 4, PHP 5)

OCIError -- Restituisce l'ultimo errore di stmt|conn|global

Descrizione

array OCIError ( [int stmt|conn|global] )

ocierror() restituisce l'ultimo errore. Se il parametro opzionale stmt|conn|global non è specificato, viene restituito l'ultimo errore generato. Se non ci sono errori, ocierror() restituisce FALSE. ocierror() restituisce l'errore in un array associativo. In questo array, code dà il codice d'errora oracle e message dà la stringa d'errore.

ociexecute

(PHP 3 >= 3.0.4, PHP 4, PHP 5)

ociexecute -- Esegue un comando SQL

Descrizione

int ociexecute ( int statement [, int mode] )

ociexecute() esegue un comando precedentemente analizzato. (vedere ociparse()). Il parametro opzionale mode permette di specificare la modalità di esecuzione (il default è OCI_COMMIT_ON_SUCCESS). Se non si desidera che i comandi eseguano un commit automatico, usare OCI_DEFAULT nella variabile mode.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

ocifetch

(PHP 3 >= 3.0.4, PHP 4, PHP 5)

ocifetch -- Estrae la prossima tupla opnendola nel buffer di risultato.

Descrizione

bool ocifetch ( int statement )

ocifetch() estrae la prossima tupla (nelle istruzioni SELECT) ponendola nel buffer interno di risultato.

ocifetchinto

(PHP 3 >= 3.0.4, PHP 4, PHP 5)

ocifetchinto -- Estrae la prossima tupla ponendola in un array

Descrizione

int ocifetchinto ( int stmt, array &result [, int mode] )

ocifetchinto() estrae la prossima tupla (nelle istruzioni SELECT) ponendola nell'array result. ocifetchinto() sovrascriverà il precedente contenuto di result. Di default result conterrà un array (primo indice = 1) di tutti i campi che non sono NULL.

Il parametro mode permette di cambiare il comportamento predefinito. E' possibile specificare più di un'opzione sommandole (es. OCI_ASSOC+OCI_RETURN_NULLS). Le opzioni valide sono:

OCI_ASSOC Restituisce un array associativo.

OCI_NUM Restituisce un array indicizzato (primo indice = 0). (DEFAULT)

OCI_RETURN_NULLS Restituisce anche i campi NULL.

OCI_RETURN_LOBS Restituisce il valore di un LOB invece del descrittore.

Esempio 1. Un semplice esempio di ocifetchinto()
<?php $conn = ocilogon("username","password"); $query = "SELECT mele FROM arance"; $statement = OCIParse ($conn, $query); OCIExecute ($statement); while (OCIFetchInto ($statement, $row, OCI_ASSOC)) { print $row['mele']; } ?>

Vedere anche ocifetch() e ociexecute().

ocifetchstatement

(PHP 3 >= 3.0.8, PHP 4, PHP 5)

ocifetchstatement -- Estrae tutte le tuple in un array

Descrizione

int ocifetchstatement ( resource stmt, array & variable )

ocifetchstatement() estrae tutte le tuple da un risultato ponendole in un array definito dall'utente. ocifetchstatement() restituisce il numero di tuple estratte.

Esempio 1. Esempio di ocifetchstatement()

<?php
/* OCIFetchStatement example mbritton@verinet.com (990624) */

$conn = OCILogon("scott","tiger");

$stmt = OCIParse($conn,"select * from emp");

OCIExecute($stmt);

$nrows = OCIFetchStatement($stmt,$results);
if ( $nrows > 0 ) {
   print "<TABLE BORDER=\"1\">\n";
   print "<TR>\n";
   while ( list( $key, $val ) = each( $results ) ) {
      print "<TH>$key</TH>\n";
   }
   print "</TR>\n";
   
   for ( $i = 0; $i < $nrows; $i++ ) {
      reset($results);
      print "<TR>\n";
      while ( $column = each($results) ) {   
         $data = $column['value'];
         print "<TD>$data[$i]</TD>\n";
      }
      print "</TR>\n";
   }
   print "</TABLE>\n";
} else {
   echo "No data found<BR>\n";
}      
print "$nrows Records Selected<BR>\n";
 
OCIFreeStatement($stmt);
OCILogoff($conn);
?>

ocifreecollection

(PHP 4 >= 4.1.0, PHP 5)

ocifreecollection -- Coming soon

Descrizione

bool ocifreecollection ( object lob )

string ociloadlob ( object lob )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

ocilogoff

(PHP 3 >= 3.0.4, PHP 4, PHP 5)

ocilogoff -- Disconnette da Oracle

Descrizione

bool ocilogoff ( resource connessione )

ocilogoff() chiude la connessione Oracle.

L'uso di ocilogoff() normalmente non è necessario, dal momento che i collegamenti non persistenti sono automaticamente chiusi alla fine dell'esecuzione dello script. Vedere anche liberare le risorse

ocilogon

(PHP 3 >= 3.0.4, PHP 4, PHP 5)

ocilogon -- Stabilisce una connessione a Oracle

Descrizione

int ocilogon ( string username, string password [, string db] )

ocilogon() restituisce un identificatore di connessione necessario per la maggior parte delle altre chiamate OCI. Il terzo parametro opzionale può contenere il nome della istanza Oracle locale o il nome della voce in tnsnames.ora a cui ci si vuole connettere. Se il terzo parametro opzionale non è specificato, PHP usa la variabile d'ambiente ORACLE_SID (istanza di Oracle) o TWO_TASK (in tnsnames.ora) per determinare a quale database collegarsi.

Le connessioni sono condivise a livello di pagina quando si usa OCILogon(). Questo significa che i commit e i rollback avvengono su tutte le transazioni aperte nella pagina, anche se sono state create connessioni multiple.

Questo esempio dimostra come le connessioni sono condivise.
Esempio 1. esempio di ocilogon()
<?php print "<HTML><PRE>"; $db = ""; $c1 = ocilogon("scott","tiger",$db); $c2 = ocilogon("scott","tiger",$db); function create_table($conn) { $stmt = ociparse($conn,"create table scott.hallo (test varchar2(64))"); ociexecute($stmt); echo $conn." created table\n\n"; } function drop_table($conn) { $stmt = ociparse($conn,"drop table scott.hallo"); ociexecute($stmt); echo $conn." dropped table\n\n"; } function insert_data($conn) { $stmt = ociparse($conn,"insert into scott.hallo values('$conn' || ' ' || to_char(sysdate,'DD-MON-YY HH24:MI:SS'))"); ociexecute($stmt,OCI_DEFAULT); echo $conn." inserted hallo\n\n"; } function delete_data($conn) { $stmt = ociparse($conn,"delete from scott.hallo"); ociexecute($stmt,OCI_DEFAULT); echo $conn." deleted hallo\n\n"; } function commit($conn) { ocicommit($conn); echo $conn." committed\n\n"; } function rollback($conn) { ocirollback($conn); echo $conn." rollback\n\n"; } function select_data($conn) { $stmt = ociparse($conn,"select * from scott.hallo"); ociexecute($stmt,OCI_DEFAULT); echo $conn."----selecting\n\n"; while (ocifetch($stmt)) echo $conn." <".ociresult($stmt,"TEST").">\n\n"; echo $conn."----done\n\n"; } create_table($c1); insert_data($c1); // Insert a row using c1 insert_data($c2); // Insert a row using c2 select_data($c1); // Results of both inserts are returned select_data($c2); rollback($c1); // Rollback using c1 select_data($c1); // Both inserts have been rolled back select_data($c2); insert_data($c2); // Insert a row using c2 commit($c2); // Commit using c2 select_data($c1); // Result of c2 insert is returned delete_data($c1); // Delete all rows in table using c1 select_data($c1); // No rows returned select_data($c2); // No rows returned commit($c1); // Commit using c1 select_data($c1); // No rows returned select_data($c2); // No rows returned drop_table($c1); print "</PRE></HTML>"; ?>

Vedere anche ociplogon() e ocinlogon().

ocinewcollection

(PHP 4 >= 4.0.6, PHP 5)

ocinewcollection -- Coming soon

Descrizione

bool ocinewcollection ( int conn, string tdo [, string shema] )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

ocinewcursor

(PHP 3 >= 3.0.8, PHP 4, PHP 5)

ocinewcursor -- Restituisce un nuovo cursore (Statement-Handle)

Descrizione

resource ocinewcursor ( resource conn )

ocinewcursor() alloca un nuovo identificatore di istruzione sulla connessione specificata.

Esempio 1. Using a REF CURSOR from a stored procedure
<?php // suppose your stored procedure info.output returns a ref cursor in :data $conn = OCILogon("scott","tiger"); $curs = OCINewCursor($conn); $stmt = OCIParse($conn,"begin info.output(:data); end;"); ocibindbyname($stmt,"data",&$curs,-1,OCI_B_CURSOR); ociexecute($stmt); ociexecute($curs); while (OCIFetchInto($curs,&$data)) { var_dump($data); } OCIFreeStatement($stmt); OCIFreeCursor($curs); OCILogoff($conn); ?>

Esempio 2. Using a REF CURSOR in a select statement
<?php print "<HTML><BODY>"; $conn = OCILogon("scott","tiger"); $count_cursor = "CURSOR(select count(empno) num_emps from emp " . "where emp.deptno = dept.deptno) as EMPCNT from dept"; $stmt = OCIParse($conn,"select deptno,dname,$count_cursor"); ociexecute($stmt); print "<TABLE BORDER=\"1\">"; print "<TR>"; print "<TH>DEPT NAME</TH>"; print "<TH>DEPT #</TH>"; print "<TH># EMPLOYEES</TH>"; print "</TR>"; while (OCIFetchInto($stmt,&$data,OCI_ASSOC)) { print "<TR>"; $dname = $data["DNAME"]; $deptno = $data["DEPTNO"]; print "<TD>$dname</TD>"; print "<TD>$deptno</TD>"; ociexecute($data["EMPCNT"]); while (OCIFetchInto($data["EMPCNT"],&$subdata,OCI_ASSOC)) { $num_emps = $subdata["NUM_EMPS"]; print "<TD>$num_emps</TD>"; } print "</TR>"; } print "</TABLE>"; print "</BODY></HTML>"; OCIFreeStatement($stmt); OCILogoff($conn); ?>

ocinewdescriptor

(PHP 3 >= 3.0.7, PHP 4, PHP 5)

ocinewdescriptor -- Inizializza un nuovo descrittore LOB/FILE vuoto

Descrizione

string ocinewdescriptor ( int connection [, int type] )

ocinewdescriptor() alloca memoria per accogliere descrittori o locatori LOB. I valori validi per il parametro type sono OCI_D_FILE, OCI_D_LOB e OCI_D_ROWID. Per i descrittori LOB, i metodi load, save, e savefile sono associati al descrittore, per i BFILE esiste solo il metodo load. Vedere i suggerimenti nel secondo esempio.

Esempio 1. esempio di ocinewdescriptor()

<?php   
    /* Questo codice deve essere richiamato da un form HTML.
     * Richiede che $user, $password, $table, $where, e $commitsize
     * siano passati dalla form.  Il codice quindi cancella
     * le tuple selezionate usando ROWID ed esegue un commit ogni
     * $commitsize righe. (Usare con attenzione, non si può fare rollback)
     */
    $conn = OCILogon($user, $password);
    $stmt = OCIParse($conn,"select rowid from $table $where");
    $rowid = OCINewDescriptor($conn,OCI_D_ROWID);
    OCIDefineByName($stmt,"ROWID",&$rowid);   
    OCIExecute($stmt);
    while ( OCIFetch($stmt) ) {      
       $nrows = OCIRowCount($stmt);
       $delete = OCIParse($conn,"delete from $table where ROWID = :rid");
       OCIBindByName($delete,":rid",&$rowid,-1,OCI_B_ROWID);
       OCIExecute($delete);      
       print "$nrows\n";
       if ( ($nrows % $commitsize) == 0 ) {
           OCICommit($conn);      
       }   
    }
    $nrows = OCIRowCount($stmt);   
    print "$nrows deleted...\n";
    OCIFreeStatement($stmt);  
    OCILogoff($conn);
?>

<?php
    /* Questo codice dimostra l'upload di file verso campi LOB.
     * Il form usato per questo esempio è del tipo seguente:
     * <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">
</form>
<?php
} else {

     // $lob_upload contiene il nome del file temporaneo

     // vedere anche la sezione delle funzionalita' di upload dei file,
     // se si vogliono usare gli upload sicuri
     
     $conn = OCILogon($user, $password);
     $lob = OCINewDescriptor($conn, OCI_D_LOB);
     $stmt = OCIParse($conn,"insert into $table (id, the_blob) 
               values(my_seq.NEXTVAL, EMPTY_BLOB()) returning the_blob into :the_blob");
     OCIBindByName($stmt, ':the_blob', &$lob, -1, OCI_B_BLOB);
     OCIExecute($stmt, OCI_DEFAULT);
     if($lob->savefile($lob_upload)){
        OCICommit($conn);
        echo "Blob successfully uploaded\n";
     }else{
        echo "Couldn't upload Blob\n";
     }
     OCIFreeDesc($lob);
     OCIFreeStatement($stmt);
     OCILogoff($conn);
  }
?>

Esempio 2. OCINewDescriptor

<?php   
    /* Chiamata di una stored procedure PL/SQLs che contiene clobs come parametri
    * di input (PHP 4 >= 4.0.6). 
    * La signature della stored prodedure PL/SQL d'esempio è:
     *
     * PROCEDURE save_data
     *   Argument Name                  Type                    In/Out Default?
     *   ------------------------------ ----------------------- ------ --------
     *   KEY                            NUMBER(38)              IN
     *   DATA                           CLOB                    IN
     *
     */

    $conn = OCILogon($user, $password);
    $stmt = OCIParse($conn, "begin save_data(:key, :data); end;");
    $clob = OCINewDescriptor($conn, OCI_D_LOB);
	OCIBindByName($stmt, ':key', $key);
	OCIBindByName($stmt, ':data', $clob, -1, OCI_B_CLOB);
	$clob->WriteTemporary($data);
	OCIExecute($stmt, OCI_DEFAULT);
	OCICommit($conn);
	$clob->close();
	$clob->free();
	OCIFreeStatement($stmt);
?>

ocinlogon

(PHP 3 >= 3.0.8, PHP 4, PHP 5)

ocinlogon -- Stabilisce, una nuova connessione a Oracle.

Descrizione

int ocinlogon ( string username, string password [, string db] )

ocinlogon() crea una nuova connessione a un database Oracle 8 e si autentica. Il terzo parametro opzionale può contenere il nome della istanza Oracle locale o il nome della voce in tnsnames.ora a cui ci si vuole connettere. Se il terzo parametro opzionale non è specificato, PHP usa la variabile d'ambiente ORACLE_SID (istanza di Oracle) o TWO_TASK (in tnsnames.ora) per determinare a quale database collegarsi.

ocinlogon() forza una nuova connessione. Si deve usare quando si ha necessità di isolare un insieme di transazioni. Di default, le connessioni sono condivise a livello di pagina se si usa ocilogon() o a livello di processo del web server se si usa ociplogon(). Se ci sono connessioni multiple aperte con ocinlogon(), tutti i commit e rollback avverranno solo sulla connessione specificata.

Questo esempio dimostra come le connessioni sono isolate.
Esempio 1. esempio di ocinlogon()
<?php print "<HTML><PRE>"; $db = ""; $c1 = ocilogon("scott","tiger",$db); $c2 = ocinlogon("scott","tiger",$db); function create_table($conn) { $stmt = ociparse($conn,"create table scott.hallo (test varchar2(64))"); ociexecute($stmt); echo $conn." created table\n\n"; } function drop_table($conn) { $stmt = ociparse($conn,"drop table scott.hallo"); ociexecute($stmt); echo $conn." dropped table\n\n"; } function insert_data($conn) { $stmt = ociparse($conn,"insert into scott.hallo values('$conn' || ' ' || to_char(sysdate,'DD-MON-YY HH24:MI:SS'))"); ociexecute($stmt,OCI_DEFAULT); echo $conn." inserted hallo\n\n"; } function delete_data($conn) { $stmt = ociparse($conn,"delete from scott.hallo"); ociexecute($stmt,OCI_DEFAULT); echo $conn." deleted hallo\n\n"; } function commit($conn) { ocicommit($conn); echo $conn." committed\n\n"; } function rollback($conn) { ocirollback($conn); echo $conn." rollback\n\n"; } function select_data($conn) { $stmt = ociparse($conn,"select * from scott.hallo"); ociexecute($stmt,OCI_DEFAULT); echo $conn."----selecting\n\n"; while (ocifetch($stmt)) echo $conn." <".ociresult($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); print "</PRE></HTML>"; ?>

Vedere anche ocilogon() e ociplogon().

ocinumcols

(PHP 3 >= 3.0.4, PHP 4, PHP 5)

ocinumcols -- Restituisce il numero di campi che risultano da un comando SQL

Descrizione

int ocinumcols ( resource stmt )

ocinumcols() restituisce il numero di campi contenuti in un'istruzione SQL.

Esempio 1. ocinumcols()

<?php   
    print "<HTML><PRE>\n";   
    $conn = OCILogon("scott", "tiger");
    $stmt = OCIParse($conn,"select * from emp");
    OCIExecute($stmt);
    while ( OCIFetch($stmt) ) {
        print "\n";   
        $ncols = OCINumCols($stmt);
        for ( $i = 1; $i <= $ncols; $i++ ) {
            $column_name  = OCIColumnName($stmt,$i);
            $column_value = OCIResult($stmt,$i);
            print $column_name . ': ' . $column_value . "\n";
        }
        print "\n";
    }
    OCIFreeStatement($stmt);  
    OCILogoff($conn);   
    print "</PRE>";
    print "</HTML>\n"; 
?>

ociparse

(PHP 3 >= 3.0.4, PHP 4, PHP 5)

ociparse -- Analizza una query e restituisce un'istruzione.

Descrizione

int ociparse ( int conn, string query )

ociparse() analizza la query rispetto alla connessione conn. Restituisce un identificatore di istruzione se la query è valida, FALSE altrimenti. La query può essere qualsiasi comando SQL o blocco di codice PL/SQL.

ociplogon

(PHP 3 >= 3.0.8, PHP 4, PHP 5)

ociplogon -- Stabilisce una connessione permanente a Oracle.

Descrizione

int ociplogon ( string username, string password [, string db] )

ociplogon() crea una connessione persistente a un database Oracle 8 e si autentica. Il terzo parametro opzionale può contenere il nome della istanza Oracle locale o il nome della voce in tnsnames.ora a cui ci si vuole connettere. Se il terzo parametro opzionale non è specificato, PHP usa la variabile d'ambiente ORACLE_SID (istanza di Oracle) o TWO_TASK (in tnsnames.ora) per determinare a quale database collegarsi.

Vedere anche ocilogon() e ocinlogon().

ociresult

(PHP 3 >= 3.0.4, PHP 4, PHP 5)

ociresult -- Restituisce il valore di campo della tupla estratta

string ocistatementtype ( resource stmt )

ocistatementtype() restituisce uno dei seguenti valori:

SELECT
UPDATE
DELETE
INSERT
CREATE
DROP
ALTER
BEGIN
DECLARE
UNKNOWN

Esempio 1. Esempi di ocistatementtype()
<?php print "<HTML><PRE>"; $conn = OCILogon("scott","tiger"); $sql = "delete from emp where deptno = 10"; $stmt = OCIParse($conn,$sql); if ( OCIStatementType($stmt) == "DELETE" ) { die "You are not allowed to delete from this table<BR>"; } OCILogoff($conn); print "</PRE></HTML>"; ?>

ociwritelobtofile

(PHP 4, PHP 5)

ociwritelobtofile -- Coming soon

Descrizione

bool ociwritelobtofile ( object lob [, string filename [, int start [, int lenght]]] )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

ociwritetemporarylob

(no version information, might be only in CVS)

ociwritetemporarylob -- Alias di OCI-Lob->writeTemporary

Descrizione

This function is an alias of: OCI-Lob->writeTemporary.

XCVI. Funzioni ODBC (Unificate)

Introduzione

In aggiunta al normale supporto ODBC, le funzioni ODBC unificate del PHP consentono l'accesso a diversi database che hanno preso in prestito la semantica dell'API ODBC per implementare le loro API. Invece di mantenere più driver per database che sono tutti pressoché identici, questi driver sono stati riuniti in un singolo insieme di funzioni ODBC.

Le funzioni ODBC unificate supportano i seguenti database: Adabas D, IBM DB2, iODBC, Solid ed Sybase SQL Anywhere.

Nota: Nella connessione ai database sopra elencati non vengono coinvolte funzioni ODBC. Le funzioni che vengono utilizzate per collegarsi nativamente con essi condividono solamente lo stesso nome e sintassi delle funzioni ODBC. L'eccezione a questo è iODBC. Compilando il PHP con il supporto di iODBC, si può utilizzare qualsiasi driver compatibile ODBC nelle applicazioni PHP. iODBC è gestito da OpenLink Software. Maggiori informazioni su iODBC, ed un HOWTO sono diponibili nel sito www.iodbc.org.

Requisiti

Per potere accedere ai database supportati occorre avere installato le librerie necessarie.

Installazione

--with-adabas[=DIR]: Include il supporto per Adabas D. DIR indica la directory di installazione di Adabas, il default è /usr/local.
--with-sapdb[=DIR]: Include il supporto per SAP DB. DIR indica la directory di installazione di SAP DB, il default è /usr/local.
--with-solid[=DIR]: Include il supporto per Solid. DIR indica la directory di installazione di Solid, il default è /usr/local/solid.
--with-ibm-db2[=DIR]: Include il supporto per IBM DB2. DIR indica la directory di installazione di DB2, il default è /home/db2inst1/sqllib.
--with-empress[=DIR]: Include il supporto per Empress. DIR indica la directory di installazione di Empress, il default è $EMPRESSPATH. A partire da PHP 4, questa opzione supporta solo Empress Versione 8.60 e successive.
--with-empress-bcs[=DIR]: Include il supporto per Empress Local Access. DIR indica la directory di installazione di Empress, il default è $EMPRESSPATH. A partire da PHP 4, questa opzione supporta solo Empress Versione 8.60 e successive.
--with-birdstep[=DIR]: Include il supporto per Birdstep. DIR indica la directory di installazione di Birdstep, il default è /usr/local/birdstep.
--with-custom-odbc[=DIR]: Include il supporto definito dall'utente per ODBC. DIR indica la directory di installazione di ODBC, il default è /usr/local. Accertarsi di definire CUSTOM_ODBC_LIBS e di avere odbc.h nelle directory di include. Ad esempio, si devorebbe definire i seguenti parametri per Sybase SQL Anywhere 5.5.00 su QNX, prima di eseguire lo script di configurazione: CPPFLAGS="-DODBC_QNX -DSQLANY_BUG" LDFLAGS=-lunix CUSTOM_ODBC_LIBS="-ldblib -lodbc".
--with-iodbc[=DIR]: Include il supporto per iODBC. DIR indica la directory di installazione di iODBC, il default è /usr/local.
--with-esoob[=DIR]: Include il supporto per Easysoft OOB. DIR indica la directory di installazione di OOB, il default è /usr/local/easysoft/oob/client.
--with-unixODBC[=DIR]: Include il supporto per unixODBC. DIR indica la directory di installazione di unixODBC, il default è /usr/local.
--with-openlink[=DIR]: Include il supporto per OpenLink ODBC. DIR indica la directory di installazione di OpenLink, il default è /usr/local. This is the same as iODBC.
--with-dbmaker[=DIR]: Include il supporto per DBMaker. DIR indica la directory di installazione di DBMaker, per default si ha la directory in cui è installata l'ultima versione di DBMaker (tipo /home/dbmaker/3.6).

Per disabilitare il supporto alle funzioni ODBC unificate in PHP 3 aggiungere il parametro --disable-unified-odbc nella linea di configurazione. Ciò è applicabile soltanto se è abilitata una delle seguenti interfaccie: iODBC, Adabas, Solid, Velocis oppure una versione personalizzata di ODBC.

La versione per Windows di PHP ha già compilato il supporto per questo modulo. Non occorre caricare alcun modulo addizionale per potere utilizzare queste funzioni.

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

Tabella 1. Parametrizzazione per il modulo Funzioni ODBC Unificate

Nome	Default	Modificabile
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

Nota: I parametri segnati con * non sono ancora implementati.

Per maggiori dettagli sulle costanti PHP_INI_* vedere Appendice G.

Breve descrizione dei parametri di configurazione.

odbc.default_db string

Sorgenti di dati ODBC da utilizzare se non viene fornita in odbc_connect() o odbc_pconnect().

odbc.default_user string

Nome utente da usare se non viene passato nelle funzioni odbc_connect() o odbc_pconnect().

odbc.default_pw string

Password da usare se non viene passato nelle funzioni odbc_connect() o odbc_pconnect().

odbc.allow_persistent boolean

Indica se permettere le connessioni ODBC persistenti.

odbc.check_persistent boolean

Verifica se una connessione è ancora valida prima di ri-utilizzarla.

odbc.max_persistent integer

Imposta il numero massimo di connessioni persistenti permesse per processo.

odbc.max_links integer

Imposta il numero massimo di connessioni permesse per processo, comprese le connessioni persistenti.

odbc.defaultlrl integer

Gestisce i campi di tipo LONG. Specifica il numero di byte da ritornare alla variabile.

When an integer is used, the value is measured in bytes. You may also use shorthand notation as described in this FAQ.

odbc.defaultbinmode integer

Gestione dei dati binari.

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

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)

Sommario
odbc_autocommit -- Valorizza il parametro autocommit
odbc_binmode -- Gestione delle colonne di dati binari
odbc_close_all -- Chiude tutte le connessioni ODBC
odbc_close -- Chiude una connessione ODBC
odbc_columnprivileges -- Restituisce un identificatore di risultato che permette di ricavare l'elenco delle colonne e dei privilegi ad esse associati.
odbc_columns -- Elenca i nomi delle colonne nella tabella specificata.
odbc_commit -- Esegue una transazione ODBC
odbc_connect -- Apre una connessione con una fonte di dati
odbc_cursor -- Restituisce il nome del cursore
odbc_data_source -- Restituisce informazionisulla connessione corrente
odbc_do -- Sinonimo di odbc_exec()
odbc_error -- Restituisce l'ultimo codice di errore
odbc_errormsg -- Restituisce l'ultimo messaggio d'errore
odbc_exec -- Prepara ed esegue una espressione SQL
odbc_execute -- Esecuzione di un'espressione memorizzata
odbc_fetch_array -- Scarica una riga da un risultato in una matrice
odbc_fetch_into -- Scarica una riga del risultato della query in un array
odbc_fetch_object -- Scarica una riga da un risultato come oggetto
odbc_fetch_row -- Estrae una riga
odbc_field_len -- Restituisce la dimensione (precisione) di un campo
odbc_field_name -- Restituisce il nome della colonna
odbc_field_num -- Restituisce il numero di colonna
odbc_field_precision -- Sinonimo di odbc_field_len()
odbc_field_scale -- Restituisce la scala di un campo
odbc_field_type -- Tipo di dato di campo
odbc_foreignkeys -- Restituisce l'elenco delle chiavi esterne per la tabella indicata, oppure la lista delle chiavi esterne in altre tabelle che fanno riferimento alla chiave primaria della tabella indicata.
odbc_free_result -- Libera le risorse associate ad un risultato
odbc_gettypeinfo -- Restituisce un identificatore di risultato contenente informazioni sui tipi di dati supportati dalla sorgente di dati
odbc_longreadlen -- Gestione di colonne LONG
odbc_next_result -- Verifica se sono disponibili più risultati
odbc_num_fields -- Numero di colonne in un esito
odbc_num_rows -- Numero di righe in un risultato
odbc_pconnect -- Apre una connessione persistente verso un database
odbc_prepare -- Predispone un'espressione all'esecuzione
odbc_primarykeys -- Restituisce un identificatore di risultato che può essere utilizzato per ricavare il nome della colonna che contiene la chiave primaria della tabella.
odbc_procedurecolumns -- Recupera informazioni sui parametri delle procedure.
odbc_procedures -- Restituisce l'elenco delle procedure memorizzate in una specifica sorgente di dati.
odbc_result_all -- Visualizza il risultato in una tabella HTML
odbc_result -- Restituisce il contenuto dei campi
odbc_rollback -- Annulla una transazione
odbc_setoption -- Impostazione dei parametri ODBC
odbc_specialcolumns -- Restituisce sia il set di colonne che identificano in modo univoco una riga nella tabella, sia colonne che sono automaticamente aggiornate quando un qualsiasi campo della riga viene aggiornato da una transazione.
odbc_statistics -- Recupera informazioni statistiche sulla tabella
odbc_tableprivileges -- Elenca le tabelle ed i privilegi ad esse associati.
odbc_tables -- Restituisce l'elenco delle tabelle presenti in una specifica sorgente di dati

odbc_autocommit

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

odbc_autocommit -- Valorizza il parametro autocommit

Descrizione

bool odbc_autocommit ( resource id_connessione [, bool OnOff] )

Se non viene fornito il parametro OnOff, la funzione restituisce lo stato dell'auto-commit per id_connessione. Il valore reso è vero se l'autocommit è attivo, altrimenti falso se non è attivato oppure si verifica un errore.

Se il campo OnOff è posto a vero, l' auto-commit è abilitato, se è valorizzato a falso l'auto-commit è disabilitato. La funzione restituisce TRUE se l'operazione riesce, FALSE se si verifica un errore.

Per default, l'auto-commit è abilitato. La disabilitazione dell'auto-commit equivale ad iniziare una transazione.

Vedere inoltre odbc_commit() e odbc_rollback().

odbc_binmode

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

odbc_binmode -- Gestione delle colonne di dati binari

Descrizione

bool odbc_binmode ( resource id_risultato, int modalità )

(Tipi di campi ODBC SQL coinvolti: BINARY, VARBINARY, LONGVARBINARY)

ODBC_BINMODE_PASSTHRU: Restituzione del dato binario direttamente al client
ODBC_BINMODE_RETURN: restituisce il dato inalterato
ODBC_BINMODE_CONVERT: Conversione in char

Quando si esegue la conversione da dati binari SQL a dati di tipo char del C, ciascun byte ( 8 bits) dei dati sorgenti vengono rappresentati da 2 caratteri ASCII. Questi caratteri sono la rappresentazione ASCII dei numeri nella loro forma esadecimale. Ad esempio, il valore binario 00000001 è convertito in "01" e il valore binario 11111111 è convertito come "FF".

Tabella 1. Gestione del tipo LONGVARBINARY

Modalità	Impostazione di longreadlen	Comportamento
ODBC_BINMODE_PASSTHRU	0	direttamente al client
ODBC_BINMODE_RETURN	0	direttamente al client
ODBC_BINMODE_CONVERT	0	direttamente al client
ODBC_BINMODE_PASSTHRU	0	passthru
ODBC_BINMODE_PASSTHRU	>0	direttamente al client
ODBC_BINMODE_RETURN	>0	restituito inalterato
ODBC_BINMODE_CONVERT	>0	restituito come char

Se viene utilizzata odbc_fetch_into(), nei casi in cui il dato viene inviato direttamente al client, quest'ultima restituisce una stringa vuota per le colonne binarie.

Se l'argomento id_risultato è valorizzato a 0, il settaggio viene applicato come default per i nuovi risultati.

Nota: I valori di default per longreadlen è 4096, mentre la modalità di default è ODBC_BINMODE_RETURN. La gestione delle colonne di campi long binary, è anche gestita dalla funzione odbc_longreadlen()

odbc_close_all

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

odbc_close_all -- Chiude tutte le connessioni ODBC

Descrizione

void odbc_close_all ( void )

La funzione odbc_close_all() chiude tutte le connessioni aperte con il database server

Nota: Se ci sono delle transazioni aperte sulla connessione richiesta, la funzione fallisce. In questo caso la connessione resta aperta.

odbc_close

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

odbc_close -- Chiude una connessione ODBC

Descrizione

void odbc_close ( resource id_connessione )

odbc_close() chiude la connessione con il database server associata all'identificativo di connessione indicato.

Nota: Se ci sono delle transazioni aperte sulla connessione richiesta, la funzione fallisce. In questo caso la connessione resta aperta.

odbc_columnprivileges

(PHP 4, PHP 5)

odbc_columnprivileges -- Restituisce un identificatore di risultato che permette di ricavare l'elenco delle colonne e dei privilegi ad esse associati.

Descrizione

resource odbc_columnprivileges ( resource id_connessione, string qualifica, string proprietario, string nome_tabella, string nome_colonna )

Elenca le colonne e i privilegi associati ad esse per la tabella data. La funzione ritorna un identificatore di risultato ODBC oppure FALSE se si verifica un errore.

Le righe risultanti dall'elaborazione contengono i seguenti campi:

TABLE_QUALIFIER
TABLE_OWNER
TABLE_NAME
GRANTOR
GRANTEE
PRIVILEGE
IS_GRANTABLE

I campi di ordinamento delle righe risultanti sono TABLE_QUALIFIER, TABLE_OWNER e TABLE_NAME.

L'argomento nome_colonna accetta dei criteri di ricerca ('%' per indicare zero o più caratteri e '_' per indicare un singolo carattere).

odbc_columns

(PHP 4, PHP 5)

odbc_columns -- Elenca i nomi delle colonne nella tabella specificata.

Descrizione

resource odbc_columns ( resource id_connessione [, string qualifica [, string schema [, string nome_tabella [, string nome_colonna]]]] )

Elenca i nomi di tutte le colonne presenti nel range richiesto. La funzione restituisce un identificatore di risultato ODBC oppure FALSE se si verifica un errore.

Le righe risultanti dall'elaborazione contengono i seguenti campi:

TABLE_QUALIFIER
TABLE_SCHKM
TABLE_NAME
COLUMN_NAME
DATA_TYPE
TYPE_NAME
PRECISION
LENGTH
SCALE
RADIX
NULLABLE
REMARKS

I campi di ordinamento delle righe risultanti sono TABLE_QUALIFIER, TABLE_SCHKM e TABLE_NAME.

Gli argomenti schema, nome_tabella e nome_colonna accettano dei criteri di ricerca ('%' per indicare zero o più caratteri e '_' per indicare un singolo carattere).

Vedere anche odbc_columnprivileges() per ottenere i privilegi associati alle colonne.

odbc_commit

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

odbc_commit -- Esegue una transazione ODBC

Descrizione

bool odbc_commit ( resource id_connessione )

La funzione odbc_commit() esegue tutte le transazioni pendenti sulla connessione indicata dall'argomento id_connessione. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

odbc_connect

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

odbc_connect -- Apre una connessione con una fonte di dati

Descrizione

resource odbc_connect ( string dsn, string utente, string password [, int tipo_cursore] )

Restituisce un identificatore di connessione ODBC oppure 0 (falso) se si verifica un errore.

L'identificatore di connessione ritornato da questa funzione è utilizzato dalle altre funzioni ODBC. Si possono avere più connessioni aperte contemporaneamente se queste utlizzano differenti database o differenti credenziali utente. Il quarto parametro (opzionale), setta il tipo di cursore da utilizzare per questa connessione. Normalmente questo parametro non è necessario, ma può essere utilizzato per aggirare dei problemi che si manifestano con alcuni driver ODBC.

Con alcuni driver ODBC, l'esecuzione di complesse procedure può generare un errore tipo: "Non si riesce ad aprire un cursore sulla procedura che richieda qualsiasi cosa oltre ad un singola istruzione select". L'uso di SQL_CUR_USE_ODBC, può evitare questo errore. Inoltre alcuni driver non supportano il parametro row_number della funzione odbc_fetch_row(). In questo caso SQL_CUR_USE_ODBC può essere d'aiuto.

Il campo tipo_cursore può assumere le seguenti costanti:

SQL_CUR_USE_IF_NEEDED
SQL_CUR_USE_ODBC
SQL_CUR_USE_DRIVER
SQL_CUR_DEFAULT

Per le connessioni persistenti vedere odbc_pconnect().

odbc_cursor

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

odbc_cursor -- Restituisce il nome del cursore

Descrizione

string odbc_cursor ( resource id_risultato )

odbc_cursor restituisce il nome del cursore per l'argomento id_risultato.

odbc_data_source

(PHP 4 >= 4.3.0, PHP 5)

odbc_data_source -- Restituisce informazionisulla connessione corrente

Descrizione

array odbc_data_source ( resource connection_id, int fetch_type )

La funzione restituisce FALSE se si verifica un errore, oppure un array se ha successo.

Questa funzione restituisce la listya dei DNS disponibili ( dopo essere stata richiamata diverse volte). E' obbligatorio che il parametro connection_id sia una connessione ODBC valida. Il parametro fetch_type può essere impostato ad una delle seguenti costanti: SQL_FETCH_FIRST oppure SQL_FETCH_NEXT. Utilizzare SQL_FETCH_FIRST la prima volta che si richiama la funzione, SQL_FETCH_NEXT le volte successive.

odbc_do

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

bool odbc_execute ( resource id_risultato [, array array_parametri] )

Esegue una espressione SQL memorizzata tramite la funzione odbc_prepare(). Restituisce TRUE in caso di successo, FALSE in caso di fallimento. L'array array_parametri occorre soltanto se è necessario fornire parametri all'espressione.

I parametri in array_parametri saranno sostituiti dai segnaposto nell'ordine dell'espressione predisposta.

Qualsiasi parametro in array_parametri che inizia e finisce con gli apici singoli sarà considerato come il nome di un file da leggere e inviare al database server come dati per gli appropriati segnaposto.

Nota: Dalla versione 4.1.1 la funzionalità di lettura del file ha le seguenti restrizioni:
La lettura del file non è soggetta alle restrizioni di modalità sicura o open-basedir. Questo sarà risolto nella versione 4.2.0 di PHP.
File remoti non sono supportati.
Se si desidera archiviare una stringa che inizia e termina con l'apice singolo, occorre farla precedere dal carattere di escape, oppure da un'altro carattere all'inizio o alla fine del parametro, per prevenire che il parametro sia considerato come nome di un file. Se questo non è possibile occorre utilizzare altri meccanismi per archiviare la stringa, quali, ad esempio, eseguire direttamente la query con odbc_exec().

odbc_fetch_array

(PHP 4 >= 4.0.2, PHP 5)

odbc_fetch_array -- Scarica una riga da un risultato in una matrice

Descrizione

array odbc_fetch_array ( resource result [, int rownumber] )

Scarica, in una matrice associativa, da una query ODBC. Vedere nel successivo log delle modifiche per sapere quando questa funzione è disponibile.

Elenco dei parametri

result: Risorsa risultato da odbc_exec().
rownumber: Opzionale, indica quale nnumero di riga recuperare.

Valori restituiti

Restituisce una matrice corrispondente alla riga scaricata, oppure FALSE se non vi sono righe successive.

Log delle modifiche

Versione	Descrizione
4.3.3	La funzione è disponibile nella vesione compilata con il supporto per IBM DB2 o UnixODBC.
4.3.2	Questa funzione esiste nella versione per Windows.
4.0.2	Questa funzione esiste nella versione compilata con il supporto DBMaker.

Vedere anche:

odbc_fetch_row()

odbc_fetch_object()

odbc_num_rows()

odbc_fetch_into

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

odbc_fetch_into -- Scarica una riga del risultato della query in un array

Descrizione

int odbc_fetch_into ( resource id_risultato, array &array_dati [, int numero_riga] )

bool odbc_fetch_into ( resource id_risultato [, int numero_riga, array &array_dati] )

La funzione restituisce il numero di colonne presenti nel risultato; FALSE se si verifica un errore. Il parametro array_dati deve essere passato per referenza, ma può essere di qualsiasi tipo dato che verrà convertito in array. Nell'array saranno posti i valori delle colonne di una riga tratta dalla tabella risultante dalla query a partire dall'indice 0.

A partire dalla versione 4.0.5 di PHP non occorre passare il parametro array_dati per riferimento.

A partire dall versione 4.0.6 di PHP il parametro numero_riga non può essere passato come costante, ma come variabile.

A partire dalla versione 4.2.0 di PHP i parametri array_dati e numero_riga sono stati invertiti. Questo permette al parametro numero_riga di essere ancora una costante. Questa è l'ultima variazione alla funzione.

Esempio 1. odbc_fetch_into() Esempi pre 4.0.6
<?php $rc = odbc_fetch_into($id_risultato, $array_di_test); ?>
oppure
<?php $rc = odbc_fetch_into($id_risultato, $riga, $array_di_test); $rc = odbc_fetch_into($id_risultato, 1, $array_di_test); ?>

Esempio 2. odbc_fetch_into() Esempi con PHP 4.0.6
<?php $rc = odbc_fetch_into($id_risultato, $array_di_test); ?>
oppure
<?php $riga = 1; $rc = odbc_fetch_into($id_risultato, $riga, $array_di_test); ?>

Esempio 3. Esempio di odbc_fetch_into()con PHP 4.2.0
<?php $rc = odbc_fetch_into($res_id, $my_array); ?>
oppure
<?php $rc = odbc_fetch_into($res_id, $my_array, 2); ?>

odbc_fetch_object

(PHP 4 >= 4.0.2, PHP 5)

odbc_fetch_object -- Scarica una riga da un risultato come oggetto

Descrizione

object odbc_fetch_object ( resource result [, int rownumber] )

Scarica un oggetto da una query ODBC. Vedere nel successivo log delle modifiche per sapere quando questa funzione è disponibile.

Elenco dei parametri

result: Risorsa risultato da odbc_exec().
rownumber: Opzionale, indica quale nnumero di riga recuperare.

Valori restituiti

Restituisce un oggetto corrispondente alla riga scaricata, oppure FALSE se non vi sono righe successive.

Log delle modifiche

Versione	Descrizione
4.3.3	La funzione è disponibile nella vesione compilata con il supporto per IBM DB2 o UnixODBC.
4.3.2	Questa funzione esiste nella versione per Windows.
4.0.2	Questa funzione esiste nella versione compilata con il supporto DBMaker.

Vedere anche:

odbc_fetch_row()

odbc_fetch_array()

odbc_num_rows()

odbc_fetch_row

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

odbc_fetch_row -- Estrae una riga

Descrizione

bool odbc_fetch_row ( resource id_risultato [, int numero_riga] )

Se odbc_fetch_row() ha successo (c'è almeno una riga), la funzione restituisce TRUE. Altrimenti, se non vi sono più righe, la funzione restituisce FALSE.

odbc_fetch_row() estrae un record dai dati restituiti dalle funzioni odbc_do() / odbc_exec(). Dopo l'esecuzione di odbc_fetch_row(), i campi della riga sono accessibili tramite la funzione odbc_result().

Se non viene specificato il parametro numero_riga, odbc_fetch_row() restituisce la riga successiva dal set delle righe risultanti dalla query. Si può intercalare esecuzioni successive di odbc_fetch_row() con e senza il parametro numero_riga.

Per spostarsi attraverso le righe risultanti, si può eseguire odbc_fetch_row() con il parametro numero_riga impostato a 1, e quindi continuare ad utilizzare odbc_fetch_row() senza numero_riga. Se il driver non supporta l'estrazione di una riga per numero, il campo numero_riga sarà ignorato.

odbc_field_len

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

odbc_field_len -- Restituisce la dimensione (precisione) di un campo

Descrizione

int odbc_field_len ( resource id_risultato, int numero_campo )

All'interno di un set di righe, referenziate dall'identificativo di risultato ODBC fornito, la funzione odbc_field_len() restituisce la dimensione (precisione) del campo indicato dall'argomento. La numerazione dei campi parte da 1.

Vedere anche: odbc_field_scale() per ottenere la scala di un numero in virgola mobile.

La funzione odbc_foreignkeys() ritorna informazioni sulle chiavi esterne. Restituisce un identificatore di risultato oppure FALSE se si verifica un errore.

Le righe risultanti dall'elaborazione contengono i seguenti campi:

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

Se l'argomento pk_tabella contiene il nome di una tabella, la funzione odbc_foreignkeys() ritorna una serie di righe contenenti i dati della chiave primaria della tabella e di tutte le chiavi esterne che hanno riferimenti a questa.

Se l'argomento fk_tabella contiene il nome di una tabella, la funzione odbc_foreignkeys() ritorna una serie di righe contenenti i dati delle chiavi esterne della tabella e delle chiavi primarie ( di altre tabelle ) a cui queste hanno riferimenti.

Se entrambi gli argomenti pk_tabella e fk_tabella contengono nomi di tabelle, odbc_foreignkeys() restituisce le chiavi esterne della tabella specificata in fk_tabella che hanno riferimenti alla chiave primaria della tabella indicata in pk_tabella. La funzione dovrebbe trovare almeno una chiave.

odbc_free_result

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

odbc_free_result -- Libera le risorse associate ad un risultato

Descrizione

bool odbc_free_result ( resource id_risultato )

Restituisce sempre TRUE.

La funzione odbc_free_result() permette di non utilizzare molta memoria durante l'esecuzione di uno script. Infatti, se si è sicuri di non avere più bisogno dei dati del risultato, si può eseguire odbc_free_result(), e la memoria associata a id_risultato sarà liberata. Se la funzione non viene utilizzata, le aree di memoria resteranno disponibili per tutta la durata dello script. Al termine verranno liberate in modo automatico.

Nota: Se si ha l'auto-commit disabilitato (vedere odbc_autocommit()) e si esegue odbc_free_result() prima di eseguire il commit, tutte le transazioni pendenti saranno annullate,

odbc_gettypeinfo

(PHP 4, PHP 5)

odbc_gettypeinfo -- Restituisce un identificatore di risultato contenente informazioni sui tipi di dati supportati dalla sorgente di dati

Descrizione

resource odbc_gettypeinfo ( resource id_connessione [, int tipo_dato] )

Recupera informazioni sui tipi di dati supportati dalla sorgente di dati. La funzione restituisce un identificatore di risultato ODBC oppure FALSE su errore. L'argomento opzionale tipo_dato può essere utilizzato per restringere l'informazione su un singolo tipo.

Le righe risultanti dall'elaborazione contengono i seguenti campi:

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

odbc_num_rows

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

odbc_num_rows -- Numero di righe in un risultato

Descrizione

int odbc_num_rows ( resource id_risultato )

odbc_num_rows() ritorna il numero di record presenti in un risultato ODBC. La funzione ritorna -1 se si verifica un errore. Per le clausole INSERT, UPDATE e DELETE, odbc_num_rows() ritorna il numero di righe coinvolte. Nella clausola SELECT questo può essere il numero di righe disponibili.

Nota: Con diversi driver, la funzione odbc_num_rows(), utilizzata con lo scopo di determinare il numero di righe dopo una SELECT, restituisce -1.

odbc_pconnect

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

odbc_pconnect -- Apre una connessione persistente verso un database

Descrizione

resource odbc_pconnect ( string dsn, string utente, string password [, int tipo_cursore] )

Restituisce un identificatore di connessione ODBC oppure 0 (FALSE) su errore. Questa funzione è molto simile a odbc_connect(), eccetto che la connessione non viene realmente chiusa quando lo script finisce. Successive richieste di connessione che utilizzino la stessa combinazione di dsn, utente, password (eseguite sia utilizzando odbc_connect(), sia utilizzando odbc_pconnect()) possono riutilizzare la connessione.

Nota: Le connessioni persistenti non hanno effetti se PHP viene utilizzato come programma CGI.

Per informazioni sul campo opzionale tipo_cursore, vedere la funzione odbc_connect(). Per maggiori dettagli sulle connessioni persistenti, fare riferimento alla FAQ di PHP.

odbc_prepare

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

odbc_prepare -- Predispone un'espressione all'esecuzione

Descrizione

resource odbc_prepare ( resource id_connessione, string testo_query )

La funzione restituisce FALSE su errore.

Restituisce un identificativo di risultato ODBC se l'espressione SQL viene predisposta correttamente. L'identificativo restituito può essere utilizzato successivamente per eseguire l'espressione utilizzando la funzione odbc_execute().

Alcuni database (tipo IBM DB2, MS SQL server e Oracle) gestiscono le le stored procedure che accettano parametri di tipo IN, INOUT e OUT come definito nelle specifiche ODBC. Tuttavia il driver Unified ODBC supporta soltanto i parametri di tipo IN.

Nel seguente codice, $res sarà valido soltanto se tutti i tre parametri per myproc sono di tipo IN:
<?php $a = 1; $b = 2; $c = 3; $stmt = odbc_prepare($conn, 'CALL myproc(?,?,?)'); $res = odbc_execute($stmt, array($a, $b, $c)); ?>
Se occorre utilizzare stored procedure che richiedono parametri INOUT od OUT, si suggerisce di utilizzare i moduli nativi del database (ad esempio, mssql per MS SQL Server, o oci8 per Oracle).

odbc_primarykeys

(PHP 4, PHP 5)

odbc_primarykeys -- Restituisce un identificatore di risultato che può essere utilizzato per ricavare il nome della colonna che contiene la chiave primaria della tabella.

Descrizione

resource odbc_primarykeys ( resource id_connessione, string qualifica, string proprietario, string tabella )

Restituisce il nome della colonna che contiene la chiave primaria per la tabella. La funzione ritorna un identificatore di risultato ODBC oppure FALSE se si verifica un errore.

Le righe risultanti dall'elaborazione contengono i seguenti campi:

TABLE_QUALIFIER
TABLE_OWNER
TABLE_NAME
COLUMN_NAME
KEY_SEQ
PK_NAME

odbc_procedurecolumns

(PHP 4, PHP 5)

odbc_procedurecolumns -- Recupera informazioni sui parametri delle procedure.

Descrizione

resource odbc_procedurecolumns ( resource id_connessione [, string qualifica, string proprietario, string procedura, string colonna] )

La funzione ritorna la lista dei parametri di input e di output e anche delle colonne che concorrono al determinazione del risultato per le procedure indicate. Viene restituito un identificatore di risultato oppure FALSE se si è un errore.

Le righe risultanti dall'elaborazione contengono i seguenti campi:

PROCEDURE_QUALIFIER
PROCEDURE_OWNER
PROCEDURE_NAME
COLUMN_NAME
COLUMN_TYPE
DATA_TYPE
TYPE_NAME
PRECISION
LENGTH
SCALE
RADIX
NULLABLE
REMARKS

I campi di ordinamento delle righe risultanti sono PROCEDURE_QUALIFIER, PROCEDURE_OWNER, PROCEDURE_NAME e COLUMN_TYPE.

Gli argomenti proprietario, procedura e colonna accettano dei criteri di ricerca ('%' per indicare zero o più caratteri e '_' per indicare un singolo carattere).

odbc_procedures

(PHP 4, PHP 5)

odbc_procedures -- Restituisce l'elenco delle procedure memorizzate in una specifica sorgente di dati.

Descrizione

resource odbc_procedures ( resource id_connessione [, string qualifica, string proprietario, string nome] )

Si ottiene l'elenco di tutte le procedure presenti nei limiti richiesti. La funzione restituisce un identificatore di risultato, oppure FALSE su errore.

Le righe risultanti dall'elaborazione contengono i seguenti campi:

PROCEDURE_QUALIFIER
PROCEDURE_OWNER
PROCEDURE_NAME
NUM_INPUT_PARAMS
NUM_OUTPUT_PARAMS
NUM_RESULT_SETS
REMARKS
PROCEDURE_TYPE

Descrizione

bool odbc_rollback ( resource id_connessione )

Annulla tutte le operazioni pendenti sulla connessione indicata da id_connessione. Se ha successo restituisce TRUE, altrimenti FALSE.

odbc_setoption

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

odbc_setoption -- Impostazione dei parametri ODBC

Descrizione

bool odbc_setoption ( resource identificativo, int funzione, int opzione, int parametro )

Questa funzione permette di manipolare i parametri ODBC per la connessione o il risultato di una query indicati. La funzione è stata sviluppata per permettere di aggirare dei problemi emersi in alcuni driver ODBC. Pertanto si dovrebbe utilizzare questa funzione soltanto se si è dei programmatori e si conoscono gli effetti generati dalle varie opzioni. Dato che ogni singola versione di driver ODBC supporta differenti parametri, occorre avere a disposizione un buon manuale del driver per avere esposti tutti i differenti settaggi che possono essere utilizzati.

Poiché i parametri possono variare in base al driver ODBC, è fortemente sconsigliato l'uso di questa funzione in script resi pubblici. Inoltre, alcune opzioni di ODBC non sono gestibili da questa funzione, dato che devono essere specificate prima di stabilire la connessione o prima della preparazione della query. Tuttavia, se per un particolare lavoro permette al PHP di funzionare, può evitare il ricorso a prodotti commerciali.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Il campo identificativo indica la connessione o l'esito su cui si varia il settaggio. Per la funzione SQLSetConnectOption(), questo indica l'identificativo di connessione, per SQLSetStmtOption(), indica l'identificativo del risultato.

Il campo funzione indica quale funzione ODBC utilizzare. Dovrebbe essere valorizzato a 1 per SQLSetConnectOption() e a 2 per SQLSetStmtOption().

Il parametro opzione indica l'opzione da settare.

Il campo parametro indica il valore per l'opzione richiesta.
Esempio 1. Esempi di utilizzo
<?php // 1. Il valore 102 per il campo opzione in SQLSetConnectOption() indica SQL_AUTOCOMMIT. // Il valore 1 per SQL_AUTOCOMMIT è SQL_AUTOCOMMIT_ON. // Pertanto questo esempio ha il medesimo effetto di: // odbc_autocommit($conn, true); odbc_setoption($conn, 1, 102, 1); // 2. Il valore 0 per il campo opzione in SQLSetStmtOption() indica SQL_QUERY_TIMEOUT. // In questo esempio si setta il timeout di una query a 30 secondi. $result = odbc_prepare($conn, $sql); odbc_setoption($result, 2, 0, 30); odbc_execute($result); ?>

odbc_specialcolumns

(PHP 4, PHP 5)

odbc_specialcolumns -- Restituisce sia il set di colonne che identificano in modo univoco una riga nella tabella, sia colonne che sono automaticamente aggiornate quando un qualsiasi campo della riga viene aggiornato da una transazione.

Descrizione

resource odbc_specialcolumns ( resource id_connessione, int tipo, string qualifica, string proprietario, string tabella, int visibilità, int nullable )

Quando l'argomento tipo è impostato a SQL_BEST_ROWID, odbc_specialcolumns() restituisce la colonna o le colonne che identificano in modo univoco ciascuna riga nella tabella.

Quando l'argomento tipo è impostato a SQL_ROWVER, odbc_specialcolumns() restituisce la colonna o le colonne della tabella indicata, se ve ne sono, che sono state aggiornate automaticamente dalla sorgente dati quando un qualsiasi campo della riga è stato aggiornato da una transazione.

La funzione restituisce un identificatore di risultato ODBC, oppure FALSE su errore.

Le righe risultanti dall'elaborazione contengono i seguenti campi:

SCOPE
COLUMN_NAME
DATA_TYPE
TYPE_NAME
PRECISION
LENGTH
SCALE
PSEUDO_COLUMN

Le righe del risultato sono ordinate in base alla colonna SCOPE.

odbc_statistics

(PHP 4, PHP 5)

odbc_statistics -- Recupera informazioni statistiche sulla tabella

Descrizione

resource odbc_statistics ( resource id_connessione, string qualifica, string proprietario, string nome_tabella, int unico, int precisione )

Si ottengono informazioni statistiche sulla tabella e i propri indici. La funzione restituisce un identificatore di risultato ODBC, oppure FALSE su errore.

Le righe risultanti dall'elaborazione contengono i seguenti campi:

TABLE_QUALIFIER
TABLE_OWNER
TABLE_NAME
NON_UNIQUE
INDEX_QUALIFIER
INDEX_NAME
TYPE
SEQ_IN_INDEX
COLUMN_NAME
COLLATION
CARDINALITY
PAGES
FILTER_CONDITION

I campi di ordinamento delle righe risultanti sono NON_UNIQUE, TYPE, INDEX_QUALIFIER, INDEX_NAME e SEQ_IN_INDEX.

odbc_tableprivileges

(PHP 4, PHP 5)

odbc_tableprivileges -- Elenca le tabelle ed i privilegi ad esse associati.

Descrizione

resource odbc_tableprivileges ( resource id_connessione, string qualifica, string proprietario, string nome )

Elenca le tabelle presenti nei limiti richiesti e, per ciascuna di queste, ne fornisce i privilegi. La funzione ritorna un identificatore di risultato ODBC, oppure FALSE su errore.

Le righe risultanti dall'elaborazione hanno i seguenti campi:

TABLE_QUALIFIER
TABLE_OWNER
TABLE_NAME
GRANTOR
GRANTEE
PRIVILEGE
IS_GRANTABLE

I campi di ordinamento delle righe risultanti sono TABLE_QUALIFIER, TABLE_OWNER e TABLE_NAME.

Gli argomenti proprietario e nome accettano dei criteri di ricerca ('%' per indicare zero o più caratteri e '_' per indicare un singolo carattere).

odbc_tables

(PHP 3 >= 3.0.17, PHP 4, PHP 5)

odbc_tables -- Restituisce l'elenco delle tabelle presenti in una specifica sorgente di dati

Descrizione

resource odbc_tables ( resource Id_connessione [, string qualifica [, string proprietario [, string nome [, string tipo]]]] )

La funzione elenca tutte le tabelle presenti nei limiti richiesti. Restituisce un identificatore di risultato in cui vi sono i dati oppure FALSE se si verifica un errore.

Le righe risultanti hanno i seguenti campi:

TABLE_QUALIFIER
TABLE_OWNER
TABLE_NAME
TABLE_TYPE
REMARKS

I campi di ordinamento delle righe risultanti sono TABLE_TYPE, TABLE_QUALIFIER, TABLE_OWNER e TABLE_NAME.

Gli argomenti proprietario e nome accettano dei criteri di ricerca ('%' per indicare zero o più caratteri e '_' per indicare un singolo carattere).

Per supportare l'enumerazione delle qualifiche, dei proprietari e dei tipi tabelle, è stata predisposta la seguente semantica per i campi qualifica, proprietario, nome, e tipo:

Se l'argomento qualifica è valorizzato con il carattere percento (%) e i parametri proprietario e nome sono delle stringhe vuote, il risultato sarà un set di righe contenente la lista delle qualifiche previste per la sorgente di dati. (Tutte le colonne tranne TABLE_QUALIFIER conterranno NULL.)
Se l'argomento proprietario è valorizzato con il carattere percento (%) e i parametri qualifica e nome sono delle stringhe vuote, il risultato sarà un set di righe contenente la lista dei proprietari previsti per la sorgente di dati. (Tutte le colonne tranne TABLE_OWNER conterranno NULL.)
Se l'argomento tipo è valorizzato con il carattere percento (%) e i parametri qualifica, proprietario e nome sono delle stringhe vuote, il risultato sarà un set di righe contenente la lista dei tipi di tabella previsti per la sorgente di dati. (Tutte le colonne tranne TABLE_TYPE conterranno NULL.)

Se l'argomento tipo non è una stinga vuota, deve contenere l'elenco dei tipi interessati separati dalla virgola; ogni singolo valore può essere, o meno, racchiuso tra apici singoli ('). Ad esempio: "'TABLE','VIEW'" o "TABLE, VIEW" sono valori validi. Se la sorgente di dati non supporta alcuni dei tipi di tabelle specificati, per questi, la funzione odbc_tables() non riporta alcuna informazione.

Vedere inoltre odbc_tableprivileges() per ottenere i privilegi associati alla tabella.

XCVII. ODBC and DB2 functions (PDO_ODBC)

Introduzione

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.

Installazione

PDO_ODBC on UNIX systems

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
./configure --enable-pdo_odbc=ibm-db2,/opt/IBM/db2/V8.1/
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.
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
./configure --enable-pdo_odbc=unixODBC,/usr/local
If you do not supply a location for the unixODBC libraries and headers to the configure command, PDO_ODBC defaults to /usr/local.
generic
./configure --enable-pdo_odbc=generic,/usr/local,libname,ldflags,cflags

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

Tabella 1. PDO_ODBC Configuration Options

Name	Default	Changeable	Changelog
pdo_odbc.connection_pooling	"strict"	PHP_INI_ALL

Per maggiori dettagli sulle costanti PHP_INI_* vedere Appendice G.

Breve descrizione dei parametri di configurazione.

pdo_odbc.connection_pooling string

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. strict is the recommend default, and will result in the use of cached connections only when all the connection parameters match exactly. relaxed will 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.

Avvertimento

relaxed matching should not be used on a shared server, for security reasons.

Suggerimento: Leave this setting at the default strict setting unless you have good reason to change it.

Sommario
PDO_ODBC DSN -- Connecting to ODBC or DB2 databases

PDO_ODBC DSN

(no version information, might be only in CVS)

PDO_ODBC DSN -- Connecting to ODBC or DB2 databases

Descrizione

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://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.

Esempi

Esempio 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

Esempio 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:DSN={IBM DB2 ODBC};HOSTNAME=localhost;PORT=50000;DBNAME=SAMPLE;PROTOCOL=TCPIP;UID=db2inst1;PWD=ibmdb2;

Esempio 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

XCVIII. oggvorbis

Introduzione

The OGG/Vorbis file format, as defined by http://www.vorbis.com/ and 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.

Requisiti

This extension requires PHP >= 4.3.0, libogg >= 1.0, and libvorbis >= 1.0.

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Installazione

oggvorbis is installed through the usual PECL package installation process.

$ pear install oggvorbis
Copy the resulting oggvorbis.so to an appropriate location and add extension=oggvorbis.so to your php.ini file or load it dynamically in your PHP script using dl('oggvorbis.so');

Context options

Tabella 1. OGG/Vorbis tuning 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')`

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

Tabella 2. OGG/Vorbis supports PCM encodings in the following formats

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.

Sommario
Usage -- Examples on using the ogg:// wrapper.

Usage

(no version information, might be only in CVS)

Usage -- Examples on using the ogg:// wrapper.

Esempi

Esempio 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); ?>

Esempio 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); ?>

XCIX. OpenAL Audio Bindings

Introduzione

Platform independent audio bindings. Requires the OpenAL library.

Installazione

This PECL extension is not bundled with PHP.

Additional information such as new releases, downloads, source files, maintainer information, and a CHANGELOG, can be located here: http://pecl.php.net/package/openal.

You may download this PECL extension DLL from the PHP Downloads page or at http://snaps.php.net/.

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Tipi di risorse

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().

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

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

Sommario
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

openal_buffer_create

(PECL)

openal_buffer_create -- Generate OpenAL buffer

Descrizione

resource openal_buffer_create ( void )

Valori restituiti

Returns an Open AL(Buffer) resource on success or FALSE on failure.

Vedere anche:

openal_buffer_loadwav()

openal_buffer_data()

openal_buffer_data

(PECL)

openal_buffer_data -- Load a buffer with data

Descrizione

bool openal_buffer_data ( resource buffer, int format, string data, int freq )

Elenco dei parametri

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_STEREO8 e AL_FORMAT_STEREO16
data: Block of binary audio data in the format and freq specified.
frew: Frequency of data given in Hz.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

openal_buffer_loadwav()

openal_stream()

openal_buffer_destroy

(PECL)

openal_buffer_destroy -- Destroys an OpenAL buffer

Descrizione

bool openal_buffer_destroy ( resource buffer )

Elenco dei parametri

buffer: An Open AL(Buffer) resource (previously created by openal_buffer_create()).

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

openal_buffer_create()

openal_buffer_get

(PECL)

openal_buffer_get -- Retrieve an OpenAL buffer property

Descrizione

int openal_buffer_get ( resource buffer, int property )

Elenco dei parametri

buffer: An Open AL(Buffer) resource (previously created by openal_buffer_create()).
property: Specific property, one of: AL_FREQUENCY, AL_BITS, AL_CHANNELS e AL_SIZE.

Valori restituiti

Returns an integer value appropriate to the property requested or FALSE on failure.

Vedere anche:

openal_buffer_create()

openal_buffer_loadwav

(PECL)

openal_buffer_loadwav -- Load a .wav file into a buffer

Descrizione

bool openal_buffer_loadwav ( resource buffer, string wavfile )

Elenco dei parametri

buffer: An Open AL(Buffer) resource (previously created by openal_buffer_create()).
wavfile: Path to .WAV file on local file system.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

openal_buffer_data()

openal_stream()

openal_context_create

(PECL)

openal_context_create -- Create an audio processing context

Descrizione

resource openal_context_create ( resource device )

Elenco dei parametri

device: An Open AL(Device) resource (previously created by openal_device_open()).

Valori restituiti

Returns an Open AL(Context) resource on success or FALSE on failure.

Vedere anche:

openal_device_open()

openal_context_destroy()

openal_context_current

(PECL)

openal_context_current -- Make the specified context current

Descrizione

bool openal_context_current ( resource context )

Elenco dei parametri

context: An Open AL(Context) resource (previously created by openal_context_create()).

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

openal_context_destroy

(PECL)

openal_context_destroy -- Destroys a context

Descrizione

bool openal_context_destroy ( resource context )

Elenco dei parametri

context: An Open AL(Context) resource (previously created by openal_context_create()).

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

openal_context_process

(PECL)

openal_context_process -- Process the specified context

Descrizione

bool openal_context_process ( resource context )

Elenco dei parametri

context: An Open AL(Context) resource (previously created by openal_context_create()).

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

openal_context_current()

openal_context_suspend()

openal_context_suspend

(PECL)

openal_context_suspend -- Suspend the specified context

Descrizione

bool openal_context_suspend ( resource context )

Elenco dei parametri

context: An Open AL(Context) resource (previously created by openal_context_create()).

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

openal_context_current()

openal_context_process()

openal_device_close

(PECL)

openal_device_close -- Close an OpenAL device

Descrizione

bool openal_device_close ( resource device )

Elenco dei parametri

device: An Open AL(Device) resource (previously created by openal_device_open()) to be closed.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

openal_device_open()

openal_device_open

(PECL)

openal_device_open -- Initialize the OpenAL audio layer

Descrizione

resource openal_device_open ( [string device_desc] )

Elenco dei parametri

device_desc: Open an audio device optionally specified by device_desc. If device_desc is not specified the first available audio device will be used.

Valori restituiti

Returns an Open AL(Device) resource on success or FALSE on failure.

Vedere anche:

openal_device_close()

openal_listener_get

(PECL)

openal_listener_get -- Retrieve a listener property

Descrizione

mixed openal_listener_get ( int property )

Elenco dei parametri

property: Property to retrieve, one of: AL_GAIN (float), AL_POSITION (array(float,float,float)), AL_VELOCITY (array(float,float,float)) e AL_ORIENTATION (array(float,float,float)).

Valori restituiti

Returns a float or array of floats (as appropriate), or FALSE on failure.

Vedere anche:

openal_listener_set()

openal_listener_set

(PECL)

openal_listener_set -- Set a listener property

Descrizione

bool openal_listener_set ( int property, mixed setting )

Elenco dei parametri

property: Property to set, one of: AL_GAIN (float), AL_POSITION (array(float,float,float)), AL_VELOCITY (array(float,float,float)) e AL_ORIENTATION (array(float,float,float)).
setting: Value to set, either float, or an array of floats as appropriate.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

openal_listener_get()

openal_source_create

(PECL)

openal_source_create -- Generate a source resource

Descrizione

resource openal_source_create ( void )

Valori restituiti

Returns an Open AL(Source) resource on success or FALSE on failure.

Vedere anche:

openal_source_set()

openal_source_destroy()

openal_source_destroy

(PECL)

openal_source_destroy -- Destroy a source resource

Descrizione

bool openal_source_destroy ( resource source )

Elenco dei parametri

source: An Open AL(Source) resource (previously created by openal_source_create()).

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

openal_source_get

(PECL)

openal_source_get -- Retrieve an OpenAL source property

Descrizione

mixed openal_source_get ( resource source, int property )

Elenco dei parametri

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)).

Valori restituiti

Returns the type associated with the property being retrieved or FALSE on failure.

Vedere anche:

openal_source_set()

openal_source_pause

(PECL)

openal_source_pause -- Pause the source

Descrizione

bool openal_source_pause ( resource source )

Elenco dei parametri

source: An Open AL(Source) resource (previously created by openal_source_create()).

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

openal_source_stop()

openal_source_rewind()

openal_source_play

(PECL)

openal_source_play -- Start playing the source

Descrizione

bool openal_source_play ( resource source )

Elenco dei parametri

source: An Open AL(Source) resource (previously created by openal_source_create()).

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

openal_source_stop()

openal_source_pause()

openal_source_rewind()

openal_source_rewind

(PECL)

openal_source_rewind -- Rewind the source

Descrizione

bool openal_source_rewind ( resource source )

Elenco dei parametri

source: An Open AL(Source) resource (previously created by openal_source_create()).

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

openal_source_stop()

openal_source_pause()

openal_source_set

(PECL)

openal_source_set -- Set source property

Descrizione

bool openal_source_set ( resource source, int property, mixed setting )

Elenco dei parametri

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 of property for a description of the value(s) expected.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

openal_source_get()

openal_source_stop

(PECL)

openal_source_stop -- Stop playing the source

Descrizione

bool openal_source_stop ( resource source )

Elenco dei parametri

source: An Open AL(Source) resource (previously created by openal_source_create()).

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

openal_source_pause()

openal_source_rewind()

openal_stream

(PECL)

openal_stream -- Begin streaming on a source

Descrizione

resource openal_stream ( resource source, int format, int rate )

Elenco dei parametri

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_STEREO8 e AL_FORMAT_STEREO16
rate: Frequency of data to stream given in Hz.

Valori restituiti

Returns a stream resource on success, or FALSE on failure.

Vedere anche:

parsekit_compile_string()

fwrite()

C. OpenSSL Functions

Introduzione

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.

Requisiti

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.4pl1 and >= 4.3.2) require OpenSSL >= 0.9.6.

Avvertimento

You are strongly encouraged to use the most recent OpenSSL version, otherwise your web server could be vulnerable to attack.

Installazione

To use PHP's OpenSSL support you must also compile PHP --with-openssl[=DIR].

Note to Win32 Users: In order to enable this module on a Windows environment, you must copy libeay32.dll from the DLL folder of the PHP/Win32 binary package to the SYSTEM32 folder of your windows machine. (Ex: C:\WINNT\SYSTEM32 or C:\WINDOWS\SYSTEM32)
Additionally, if you are planning to use the key generation and certificate signing functions, you will need to install a valid openssl.cnf on your system. As of PHP 4.3.0, we include a sample configuration file in the openssl folder of our win32 binary distribution. If you are using PHP 4.2.0 or later and are missing the file, you can obtain it from the OpenSSL home page or by downloading the PHP 4.3.0 release and using the configuration file from there.
Note to Win32 Users: PHP will search for the openssl.cnf using the following logic:
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.

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 configargs of the functions that require a configuration file.

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Tipi di risorse

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
1. An X.509 resource returned from openssl_x509_read()
2. A string having the format file://path/to/cert.pem; the named file must contain a PEM encoded certificate
3. A string containing the content of a certificate, PEM encoded
Public/Private Keys
1. A key resource returned from openssl_get_publickey() or openssl_get_privatekey()
2. For public keys only: an X.509 resource
3. 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)
4. A string containing the content of a certificate/key, PEM encoded
5. 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.

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

Purpose checking flags

X509_PURPOSE_SSL_CLIENT (integer)
X509_PURPOSE_SSL_SERVER (integer)
X509_PURPOSE_NS_SSL_SERVER (integer)
X509_PURPOSE_SMIME_SIGN (integer)
X509_PURPOSE_SMIME_ENCRYPT (integer)
X509_PURPOSE_CRL_SIGN (integer)
X509_PURPOSE_ANY (integer)

Padding flags

OPENSSL_PKCS1_PADDING (integer)
OPENSSL_SSLV23_PADDING (integer)
OPENSSL_NO_PADDING (integer)
OPENSSL_PKCS1_OAEP_PADDING (integer)

Key types

OPENSSL_KEYTYPE_RSA (integer)
OPENSSL_KEYTYPE_DSA (integer)
OPENSSL_KEYTYPE_DH (integer)

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:

Tabella 1. PKCS7 CONSTANTS

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 options 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

Nota: These constants were added in 4.0.6.

Sommario
openssl_csr_export_to_file -- Exports a CSR to a file
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_error_string -- Return openSSL error message
openssl_free_key -- Free key resource
openssl_get_privatekey -- Alias di openssl_pkey_get_private()
openssl_get_publickey -- Alias di openssl_pkey_get_public()
openssl_open -- Open sealed data
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_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_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

Nota: You need to have a valid openssl.cnf installed for this function to operate correctly. See the notes under the installation section for more information.

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 in configargs behave as their equivalents in the openssl.conf, as listed in the table below.

Tabella 1. Configuration overrides

`configargs` key	type	`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	string	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_DH` or `OPENSSL_KEYTYPE_RSA`. The default value is `OPENSSL_KEYTYPE_RSA` which is currently the only supported key type.
encrypt_key	boolean	encrypt_key	Should an exported key (with passphrase) be encrypted?

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempio 1. openssl_csr_new() example - 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

Description

resource openssl_csr_sign ( mixed csr, mixed cacert, mixed priv_key, int days [, array configargs [, int serial]] )

openssl_csr_sign() generates an x509 certificate resource from the csr previously generated by openssl_csr_new(), but 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(). The generated certificate will be signed by cacert. If cacert is NULL, the generated certificate will be a self-signed certificate. priv_key is the private key that corresponds to cacert. days specifies the length of time for which the generated certificate will be valid, in days. You can finetune the CSR signing by configargs. See openssl_csr_new() for more information about configargs. Since PHP 4.3.3 you can specify the serial number of issued certificate by serial. In earlier versions, it was always 0.

Returns an x509 certificate resource on success, FALSE on failure.

Nota: You need to have a valid openssl.cnf installed for this function to operate correctly. See the notes under the installation section for more information.

Esempio 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"); $userscert = 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_error_string

(PHP 4 >= 4.0.6, PHP 5)

openssl_error_string -- Return openSSL error message

Description

string openssl_error_string ( void )

Returns an error message string, or FALSE if there are no more error messages to return.

openssl_error_string() returns the last error from the openSSL library. Error messages are stacked, so this function should be called multiple times to collect all of the information.

Esempio 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

Description

void openssl_free_key ( resource key_identifier )

openssl_free_key() frees the key associated with the specified key_identifier from memory.

openssl_get_privatekey

(PHP 4 >= 4.0.4, PHP 5)

openssl_get_privatekey -- Alias di openssl_pkey_get_private()

Descrizione

This function is an alias of: openssl_pkey_get_private().

openssl_get_publickey

(PHP 4 >= 4.0.4, PHP 5)

openssl_get_publickey -- Alias di openssl_pkey_get_public()

Descrizione

This function is an alias of: openssl_pkey_get_public().

openssl_open

(PHP 4 >= 4.0.4, PHP 5)

openssl_open -- Open sealed data

Description

bool openssl_open ( string sealed_data, string &open_data, string env_key, mixed priv_key_id )

Restituisce TRUE in caso di successo, FALSE in caso di fallimento. If successful the opened data is returned in open_data.

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.

Esempio 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_pkcs7_decrypt

(PHP 4 >= 4.0.6, PHP 5)

openssl_pkcs7_decrypt -- Decrypts an S/MIME encrypted message

Description

bool openssl_pkcs7_decrypt ( string 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.

resource openssl_pkey_get_public ( mixed certificate )

Returns a positive key resource identifier on success, or FALSE on error.

openssl_get_publickey() extracts the public key from certificate and prepares it for use by other functions. certificate can 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.

openssl_pkey_new

(PHP 4 >= 4.2.0, PHP 5)

openssl_pkey_new -- Generates a new private key

Description

resource openssl_pkey_new ( [array 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(). You can finetune the key generation (such as specifying the number of bits) using configargs. See openssl_csr_new() for more information about configargs.

Nota: You need to have a valid openssl.cnf installed for this function to operate correctly. See the notes under the installation section for more information.

openssl_x509_checkpurpose -- Verifies if a certificate can be used for a particular purpose

Description

int openssl_x509_checkpurpose ( mixed x509cert, int purpose [, array cainfo [, string untrustedfile]] )

Returns TRUE if the certificate can be used for the intended purpose, FALSE if it cannot, or -1 on error.

openssl_x509_checkpurpose() examines the certificate specified by x509cert to see if it can be used for the purpose specified by purpose.

cainfo should be an array of trusted CA files/dirs as described in Certificate Verification. It defaults to an empty array.

untrustedfile, if specified, is the name of a PEM encoded file holding certificates that can be used to help verify the certificate, although no trust in placed in the certificates that come from that file.

Tabella 1. 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?

(PHP 4 >= 4.0.6, PHP 5)

openssl_x509_parse -- Parse an X509 certificate and return the information as an array

Description

array openssl_x509_parse ( mixed x509cert [, bool shortnames] )

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. shortnames controls how the data is indexed in the array - if shortnames is TRUE (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.

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

Description

resource openssl_x509_read ( mixed x509certdata )

openssl_x509_read() parses the certificate supplied by x509certdata and returns a resource identifier for it.

CI. Funzioni Oracle

Introduzione

Questa estensione permette l'accesso ai server database Oracle. Vedere anche l'estensione OCI8.

Installazione

You have to compile PHP with the option --with-oracle[=DIR], where DIR defaults to your environment variable ORACLE_HOME.

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

ORA_BIND_INOUT (integer)
ORA_BIND_IN (integer)
ORA_BIND_OUT (integer)
ORA_FETCHINTO_ASSOC (integer)
ORA_FETCHINTO_NULLS (integer)

Sommario
Ora_Bind -- effettua il binding di una variabile PHP ad un parametro di Oracle
Ora_Close -- chiude un cursore Oracle
ora_columnname -- restituisce il nome di un campo risultato Oracle
ora_columnsize -- restituisce la dimensione di un campo risultato Oracle
ora_columntype -- restituisce il tipo di un campo risultato Oracle
ora_commit -- esegue una transazione Oracle
ora_commitoff -- disabilita il commit automatico
Ora_CommitOn -- abilita il commit automatico
Ora_Do -- Parse, Exec, Fetch
ora_error -- restituisce il messaggio di errore di Oracle
ora_errorcode -- restituisce il codice di errore di Oracle
ora_exec -- esegue dei comandi già analizzati su un cursore Oracle
Ora_Fetch_Into -- Scarica una tupla nell'array specificato
Ora_Fetch -- scarica una tupla di dati da un cursore
ora_getcolumn -- restituisce i dati di un campo acquisito
ora_logoff -- chiude una connessione Oracle
ora_logon -- apre una connessione Oracle
ora_numcols -- Restituisce il numero di campi/colonne
ora_numrows -- Restituisce il numero di tuple
ora_open -- apre un cursore Oracle
ora_parse -- analizza un comando SQL
ora_plogon -- Apre una connessione Oracle permanente
Ora_Rollback -- esegue il rollback della transazione

Ora_Bind

(PHP 3, PHP 4, PHP 5 <= 5.1.0RC1)

Ora_Bind -- effettua il binding di una variabile PHP ad un parametro di Oracle

Descrizione

int ora_bind ( int cursor, string PHP variable name, string SQL parameter name, int length [, int type] )

Restituisce TRUE se il binding riesce, altrimenti FALSE. I dettagli dell'errore si ottengono usando le funzioni ora_error() e ora_errorcode().

Questa funzione collega la variabile PHP indicata con un parametro SQL. Il parametro SQL deve essere nella forma ":name". Con il parametro facoltativo type, si può determinare se il parametro SQL è di in/out (0, default), in (1) oppure out (2). Dalla versione 3.0.1 di PHP, su possono utilizzare le costanti ORA_BIND_INOUT, ORA_BIND_IN e ORA_BIND_OUT al posto dei numeri.

ora_bind deve essere invocata dopo ora_parse() e prima di ora_exec(). I valori di input possono essere dati mediante assegnamento alle variabili PHP collegate; dopo aver chiamato ora_exec() le variabili PHP collegate contengono i valori di output, se disponibili.

<?php
ora_parse($curs, "declare tmp INTEGER; begin tmp := :in; :out := tmp; :x := 7.77; end;");
ora_bind($curs, "result", ":x", $len, 2);
ora_bind($curs, "input", ":in", 5, 1);
ora_bind($curs, "output", ":out", 5, 2);
$input = 765;
ora_exec($curs);
echo "Result: $result<BR>Out: $output<BR>In: $input";
?>

Ora_Close

(PHP 3, PHP 4, PHP 5 <= 5.1.0RC1)

Ora_Close -- chiude un cursore Oracle

Descrizione

int ora_close ( int cursor )

string ora_columntype ( resource cursor, int column )

Restituisce il tipo Oracle del campo/colonna column nel cursore cursor. La colonna 0 è la pirma. Il tipo restituito sarà uno dei seguenti:

"VARCHAR2"

"VARCHAR"

"CHAR"

"NUMBER"

"LONG"

"LONG RAW"

int ora_do ( int conn, string query )

Questa funzione è la combinazione veloce di ora_parse(), ora_exec() e ora_fetch(). Analizza, ed esegue un comando SQL, quindi scarica la prima tupla del risultato.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento. I dettagli dell'errore si ottengono usando le funzioni ora_error() e ora_errorcode().

Vedere anche ora_parse(),ora_exec(), e ora_fetch().

ora_error

(PHP 3, PHP 4, PHP 5 <= 5.1.0RC1)

ora_error -- restituisce il messaggio di errore di Oracle

Descrizione

string ora_error ( int cursor_or_connection )

Restituisce un messaggio d'errore nella forma XXX-NNNNN dove XXX è la sorgente dell'errore e NNNNN identifica il messaggio d'errore.

Nota: Il supporto per gli id di connessione è stato aggiunto nella versione 3.0.4.

Nelle versioni UNIX di Oracle, è possibile ottenere i dettagli dell'errore in questo modo: $ oerr ora 00001 00001, 00000, "unique constraint (%s.%s) violated" // *Cause: An update or insert statement attempted to insert a duplicate key // For Trusted ORACLE configured in DBMS MAC mode, you may see // this message if a duplicate entry exists at a different level. // *Action: Either remove the unique restriction or do not insert the key

ora_errorcode

(PHP 3, PHP 4, PHP 5 <= 5.1.0RC1)

ora_errorcode -- restituisce il codice di errore di Oracle

Descrizione

int ora_errorcode ( int cursor_or_connection )

Restituisce il codice numerico di errore dell'ultimo comando eseguito sul cursore o sulla connessione specificata.

Nota: Il supporto per gli id di connessione è stato aggiunto nella versione 3.0.4.

ora_exec

(PHP 3, PHP 4, PHP 5 <= 5.1.0RC1)

ora_exec -- esegue dei comandi già analizzati su un cursore Oracle

Descrizione

bool ora_exec ( resource cursor )

ora_exec() esegue il comando cursor, già analizzato da ora_parse().

Restituisce TRUE in caso di successo, FALSE in caso di fallimento. I dettagli dell'errore si ottengono usando le funzioni ora_error() e ora_errorcode().

Vedere anche ora_parse(), ora_fetch() e ora_do().

Ora_Fetch_Into

(PHP 3, PHP 4, PHP 5 <= 5.1.0RC1)

Ora_Fetch_Into -- Scarica una tupla nell'array specificato

Descrizione

int ora_fetch_into ( int cursor, array result [, int flags] )

Recupera una tupla e la mette in un array. Il parametro flags ha due valori: se il flag ORA_FETCHINTO_NULLS è impostato, i campi con valori NULL vengono inseriti nell'array; se il flag ORA_FETCHINTO_ASSOC è impostato, viene creato un array associativo.

Restituisce il numero di campi acquisiti.

Esempio 1. ora_fetch_into()
<?php $risultato = array(); ora_fetch_into($cursore, $results); echo $risultato[0]; echo $risultato[1]; $risultato = array(); ora_fetch_into($cursore, $risultato, ORA_FETCHINTO_NULLS|ORA_FETCHINTO_ASSOC); echo $risultato['MioCampo']; ?>

Vedere anche ora_parse(),ora_exec(), ora_fetch() e ora_do().

Ora_Fetch

(PHP 3, PHP 4, PHP 5 <= 5.1.0RC1)

Ora_Fetch -- scarica una tupla di dati da un cursore

Descrizione

int ora_fetch ( int cursor )

Acquisisce una tupla di dati dal cursore specificato.

Restituisce TRUE (la tupla è stata acquisita) o FALSE (non ci sono più tuple, o è avvenuto un errore). Se è avvenuto un errore, i dettagli si ottengono usando le funzioni ora_error() e ora_errorcode(). Se non sono avvenuti errori, ora_errorcode() restituirà 0.

Vedere anche ora_parse(),ora_exec(), e ora_do().

ora_getcolumn

(PHP 3, PHP 4, PHP 5 <= 5.1.0RC1)

ora_getcolumn -- restituisce i dati di un campo acquisito

Descrizione

mixed ora_getcolumn ( int cursor, mixed column )

Restituisce i dati del campo o del risultato di una funzione.

Restituisce il contenuto del campo/colonna. Se avviene un errore, viene restituito il valore FALSE e ora_errorcode() restituirà un valore diverso da zero. Si noti, comunque, che un test al valore FALSE sul risultato di questa funzione può dare esito positivo anche in caso non ci siano errori (campo NULL, stringa vuota, il numero 0, la stringa "0").

ora_logoff

(PHP 3, PHP 4, PHP 5 <= 5.1.0RC1)

ora_logoff -- chiude una connessione Oracle

Descrizione

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche ora_exec(), ora_fetch() e ora_do().

ora_plogon

(PHP 3, PHP 4, PHP 5 <= 5.1.0RC1)

ora_plogon -- Apre una connessione Oracle permanente

Descrizione

int ora_plogon ( string user, string password )

Stabilisce una connessione permanente tra PHP ed un database Oracle con le username and password specificate.

Vedere anche ora_logon().

Ora_Rollback

(PHP 3, PHP 4, PHP 5 <= 5.1.0RC1)

Ora_Rollback -- esegue il rollback della transazione

Descrizione

int ora_rollback ( int connection )

Questa funzione annulla una transazione Oracle. (Vedere ora_commit() per la definizione di una transazione.)

Restituisce TRUE in caso di successo, FALSE in caso di fallimento. I dettagli dell'errore si ottengono usando le funzioni ora_error() e ora_errorcode() functions.

CII. Oracle Functions (PDO_OCI)

Introduzione

Avvertimento

PDO_OCI is a driver that implements the PHP Data Objects (PDO) interface to enable access from PHP to Oracle databases through the OCI library.

Sommario
PDO_OCI DSN -- Connecting to Oracle databases

PDO_OCI DSN

(no version information, might be only in CVS)

PDO_OCI DSN -- Connecting to Oracle databases

Descrizione

The PDO_OCI Data Source Name (DSN) is composed of the following elements:

DSN prefix: The DSN prefix is oci:. If you are connecting to a database defined in tnsnames.ora, append the name of the database to the DSN prefix and your DSN is complete.
dbname (Oracle Instant Client): The URI for the Oracle Instant Client connection takes the form of dbname=//hostname:port-number/database.

Esempi

Esempio 1. PDO_OCI DSN examples
The following examples show a PDO_OCI DSN for connecting to Oracle databases:
oci:mydb oci:dbname=//localhost:1521/mydb

CIII. Output Control Functions

Introduzione

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.

Requisiti

Non sono necessarie librerie esterne per utilizzare questo modulo.

Installazione

Non è necessaria nessuna installazione per usare queste funzioni, esse fanno parte del core di PHP.

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

Tabella 1. Output Control configuration options

Name	Default	Changeable	Changelog
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.

Per maggiori dettagli sulle costanti PHP_INI_* vedere Appendice G.

Breve descrizione dei parametri di configurazione.

output_buffering boolean/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_handler string

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.

Nota: You cannot use both mb_output_handler() with ob_iconv_handler() and you cannot use both ob_gzhandler() and zlib.output_compression.

Nota: Only built-in functions can be used with this directive. For user defined functions, use ob_start().

implicit_flush boolean

FALSE by default. Changing this to TRUE tells 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 TRUE when operating under the CLI SAPI.

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

Questa estensione non definisce alcuna costante.

Esempi

Esempio 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.)

Nota: When upgrading from PHP 4.1 (and 4.2) to 4.3 that due to a bug in earlier versions you must ensure that implict_flush is OFF in your php.ini, otherwise any output with ob_start() will not be hidden from output.

Vedere anche:

See also header() and setcookie().

Sommario
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

flush

(PHP 3, PHP 4, PHP 5)

flush -- Flush the output buffer

Description

void flush ( void )

Flushes the output buffers of PHP and whatever backend PHP is using (CGI, a web server, etc). This effectively tries to push all the output so far to the user's browser.

flush() has no effect on the buffering scheme of your webserver or the browser on the client side. Thus you need to call both ob_flush() and flush() to flush the output buffers.

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.

ob_clean

(PHP 4 >= 4.2.0, PHP 5)

ob_clean -- Clean (erase) the output buffer

Description

void ob_clean ( void )

This function discards the contents of the output buffer.

This function does not destroy the output buffer like ob_end_clean() does.

ob_end_clean

(PHP 4, PHP 5)

ob_end_clean -- Clean (erase) the output buffer and turn off output buffering

Description

bool ob_end_clean ( void )

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_flush() is called. The function returns TRUE when it successfully discarded one buffer and FALSE otherwise. 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).

The following example shows an easy way to get rid of all output buffers:

Esempio 1. ob_end_clean() example
<?php while (@ob_end_clean()); ?>

Nota: If the function fails it generates an E_NOTICE.
The boolean return value was added in PHP 4.2.0.

ob_end_flush

(PHP 4, PHP 5)

ob_end_flush -- Flush (send) the output buffer and turn off output buffering

Description

bool ob_end_flush ( void )

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. The function returns TRUE when it successfully discarded one buffer and FALSE otherwise. 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).

Nota: This function is similar to ob_get_flush(), except that ob_get_flush() returns the buffer as a string.

The following example shows an easy way to flush and end all output buffers:

Esempio 1. ob_end_flush() example
<?php while (@ob_end_flush()); ?>

Nota: If the function fails it generates an E_NOTICE.
The boolean return value was added in PHP 4.2.0.

Nota: ob_gzhandler() requires the zlib extension.

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.

Nota: mode was added in PHP 4.0.5.

Esempio 1. ob_gzhandler() example
<?php ob_start("ob_gzhandler"); ?> <html> <body> <p>This should be a compressed page.</p> </html> <body>

Nota: You cannot use both ob_gzhandler() and zlib.output_compression. Also note that using zlib.output_compression is preferred over ob_gzhandler().

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.

An optional output_callback function may be specified. This function takes a string as a parameter and should return a string. The function will be called when ob_end_flush() is called, or when the output buffer is flushed to the browser at the end of the request. When output_callback is 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 the output_callback is not a callable function, this function will return FALSE. 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_CONT and PHP_OUTPUT_HANDLER_END.

Nota: 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.

Nota: Before PHP 4.3.2 this function did not return FALSE in case the passed output_callback can not be executed.

Avvertimento

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.

If the optional parameter chunk_size is passed, the callback function is called on every first newline after chunk_size bytes of output. The output_callback parameter may be bypassed by passing a NULL value.

If the optional parameter erase is set to FALSE, the buffer will not be deleted until the script finishes (as of PHP 4.3.0).

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.

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.

Esempio 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(); ?>
Would produce:
<html> <body> <p>It's like comparing oranges to oranges.</p> </body> </html>

output_add_rewrite_var

(PHP 4 >= 4.3.0, PHP 5)

output_add_rewrite_var -- Add URL rewriter values

Description

bool output_add_rewrite_var ( string name, string value )

This function rewrite the URLs and forms with the given variable.

Nota: This function buffers the output.

Esempio 1. output_add_rewrite_var() example
<?php output_add_rewrite_var('var', 'value'); // a link echo '<a href="file.php">link</a>'; // a form echo '<form action="script.php" method="post"> <input type="text" name="var2" /> </form>'; print_r(ob_list_handlers()); ?>
Il precedente esempio visualizzerà:
<a href="file.php?var=value">link</a> <form action="script.php" method="post"> <input type="hidden" name="var" value="value" /> <input type="text" name="var2" /> </form> Array ( [0] => URL-Rewriter )

output_reset_rewrite_vars

(PHP 4 >= 4.3.0, PHP 5)

output_reset_rewrite_vars -- Reset URL rewriter values

Description

bool output_reset_rewrite_vars ( void )

This function resets the URL rewriter and undo the changes made by output_add_rewrite_var() and/or by session_start() that are still in the buffer.

Esempio 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>'; ?>
Il precedente esempio visualizzerà:
<a href="file.php?PHPSESSID=xxx&var=value">link</a> <a href="file.php">link</a>

CIV. Ovrimos SQL Functions

Introduzione

Ovrimos SQL Server, is a client/server, transactional RDBMS combined with Web capabilities and fast transactions.

Nota: Questo modulo è stato spostato nel repository PECL e non sarà più rilascio con il PHP dalla versione 5.1.0.

Nota: Questo modulo non è disponibile su piattaforme Windows.

Requisiti

You'll need to install the sqlcli library available in the Ovrimos SQL Server distribution.

Installazione

To enable Ovrimos support in PHP just compile PHP with the --with-ovrimos[=DIR] parameter to your configure line. DIR is the Ovrimos' libsqlcli install directory.

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Tipi di risorse

Esempi

Esempio 1. Connect to Ovrimos SQL Server and select from a system table
<?php $conn = ovrimos_connect("server.domain.com", "8001", "admin", "password"); if ($conn != 0) { echo "Connection ok!"; $res = ovrimos_exec($conn, "select table_id, table_name from sys.tables"); if ($res != 0) { echo "Statement ok!"; ovrimos_result_all($res); ovrimos_free_result($res); } ovrimos_close($conn); } ?>
This will just connect to an Ovrimos SQL server.

Sommario
ovrimos_close -- Closes the connection to ovrimos
ovrimos_commit -- Commits the transaction
ovrimos_connect -- Connect to the specified database
ovrimos_cursor -- Returns the name of the cursor
ovrimos_exec -- Executes an SQL statement
ovrimos_execute -- Executes a prepared SQL statement
ovrimos_fetch_into -- Fetches a row from the result set
ovrimos_fetch_row -- Fetches a row from the result set
ovrimos_field_len -- Returns the length of the output column
ovrimos_field_name -- Returns the output column name
ovrimos_field_num -- Returns the (1-based) index of the output column
ovrimos_field_type -- Returns the (numeric) type of the output column
ovrimos_free_result -- Frees the specified result_id
ovrimos_longreadlen -- Specifies how many bytes are to be retrieved from long datatypes
ovrimos_num_fields -- Returns the number of columns
ovrimos_num_rows -- Returns the number of rows affected by update operations
ovrimos_prepare -- Prepares an SQL statement
ovrimos_result_all -- Prints the whole result set as an HTML table
ovrimos_result -- Retrieves the output column
ovrimos_rollback -- Rolls back the transaction

bool ovrimos_fetch_into ( int result_id, array &result_array [, string how [, int rownumber]] )

ovrimos_fetch_into() fetches a row from the result set into result_array, which should be passed by reference. Which row is fetched is determined by the two last parameters. how is one of Next (default), Prev, First, Last, Absolute, corresponding to forward direction from current position, backward direction from current position, forward direction from the start, backward direction from the end and absolute position from the start (essentially equivalent to 'first' but needs 'rownumber'). Case is not significant. rownumber is optional except for absolute positioning. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempio 1. A fetch into example
<?php $conn=ovrimos_connect("neptune", "8001", "admin", "password"); if ($conn!=0) { echo "Connection ok!"; $res=ovrimos_exec($conn, "select table_id, table_name from sys.tables"); if ($res != 0) { echo "Statement ok!"; 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 "Next: error\n"; } } else { echo "First: error\n"; } ovrimos_free_result($res); } ovrimos_close($conn); } ?>
This example will fetch a row.

ovrimos_fetch_row

(PHP 4 >= 4.0.3, PHP 5)

ovrimos_fetch_row -- Fetches a row from the result set

Description

bool ovrimos_fetch_row ( int result_id [, int how [, int row_number]] )

int ovrimos_prepare ( int connection_id, string query )

Nota: This module has not been tested on other platforms than Debian/GNU Linux for PPC.

Nota: This module is also in development and may change, though I don't expect major changes to the API.

Requisiti

You need at least PHP 5.0.0 and libpx >= 0.1.9. The paradox library (libpx) is available at http://pxlib.sourceforge.net.

Installazione

A short installation note: just type
$ pear install paradox
in your console.

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Object oriented API

The paradox extension provides also an object oriented API. It consists of only one class called paradox_doc. 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.

Tabella 1. Methods of class paradox_doc

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()
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()
timestamp2string()	px_timestamp2string()

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

The following two tables lists all constants defined by the paradox extension.

Tabella 2. Contants for field types

Name	Meaning
PX_FIELD_ALPHA	Character data with fixed length
PX_FIELD_DATE	Date
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 (not supported)
PX_FIELD_BLOB	Binary large object (not supported)
PX_FIELD_FMTMEMOBLOB	Binary large object (not supported)
PX_FIELD_OLE	OLE object (basically a blob, not supported)
PX_FIELD_GRAPHIC	Graphic (basically a blob, not supported)
PX_FIELD_TIME	time
PX_FIELD_TIMESTAMP	timestamp (like the unix timestamp)
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
PX_KEYTOUPPER

Tabella 3. Contants for file types

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 (not supported)
PX_FILE_SEC_INDEX	Secondary index (not supported)
PX_FILE_INC_SEC_INDEX	Incremental secondary index (not supported)
PX_FILE_NON_INC_SEC_INDEX_G	(not supported)
PX_FILE_SEC_INDEX_G	(not supported)
PX_FILE_INC_SEC_INDEX_G	(not supported)

Sommario
px_close -- Closes a paradox database
px_create_fp -- Create a new 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_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_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_close

(PECL)

px_close -- Closes a paradox database

Descrizione

bool px_close ( resource pxdoc )

Closes the paradox database. This function will not close the file. You will have to call fclose() afterwards.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

px_open_fp()

another_func()

The example at px_new()

px_create_fp

(PECL)

px_create_fp -- Create a new paradox database

Descrizione

bool px_create_fp ( resource 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. The first parameter is the return value of px_new(). fielddesc is an array containing one element for each field containing its specification. Each 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, you will have to provide a third element specifying the length of the field.

Nota: 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.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 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_tablename($pxdoc, "testtable"); for($i=-50; $i<50; $i++) { $rec = array($i, -$i); px_put_record($pxdoc, $rec); } px_close($pxdoc); px_delete($pxdoc); fclose($fp); ?>

Vedere anche:

px_new()

px_put_record()

fopen()

px_delete

(PECL)

px_delete -- Deletes resource of paradox database

Descrizione

bool px_delete ( resource pxdoc )

Deletes the resource of the paradox file and frees all memory.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

px_get_field

(PECL)

px_get_field -- Returns the specification of a single field

Descrizione

array px_get_field ( resource pxdoc, int fieldno )

Valori restituiti

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)

px_get_info -- Return lots of information about a paradox file

Descrizione

array px_get_info ( resource pxdoc )

Valori restituiti

Returns an associated array with lots of information about a paradox file. This array is likely to extend in the future.

fileversion: Version of file multiplied by 10.
tablename: Name of table as stored in the file.
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.
maxtablesize: This value multiplied by 0x400 is the size of a data block in bytes.
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 as 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().

Vedere anche:

px_numfields()

px_numrecords()

px_get_parameter

(PECL)

px_get_parameter -- Gets a parameter

Descrizione

string px_get_parameter ( resource pxdoc, string name )

Gets various parameters.

Elenco dei parametri

The name can 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 being recode into the targetencoding.
inputencoding: The encoding of the input data which is to be stored into the database.

px_get_record

(PECL)

px_get_record -- Returns record of paradox database

Descrizione

array px_get_record ( resource pxdoc, int num [, int mode] )

Elenco dei parametri

pxdoc
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 mode can be PX_KEYTOLOWER or PX_KEYTOUPPER in order to convert the keys into lower or upper case. If mode is 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 type PX_FIELD_TIME will 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.

Valori restituiti

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)

px_get_schema -- Returns the database schema

Descrizione

array px_get_schema ( resource pxdoc [, int mode] )

px_get_schema() returns the database schema.

Elenco dei parametri

pxdoc
mode: If the optional mode is PX_KEYTOLOWER or PX_KEYTOUPPER the key will be converted to lower or upper case. If mode is 0 or not passed at all, then the key name will be identical to the field name.

Valori restituiti

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.

px_get_value

(PECL)

px_get_value -- Gets a value

Descrizione

float px_get_value ( resource pxdoc, string name )

Gets various values.

Elenco dei parametri

pxdoc

name

name can be one of the following.

numprimkeys: The number of primary keys. Paradox databases always use the first numprimkeys fields for the primary index.

px_new

(PECL)

px_new -- Create a new paradox object

Descrizione

resource px_new ( void )

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 justs creates an instance of a paradox object.

Valori restituiti

Returns FALSE on failure.

Esempi

Esempio 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.
Esempio 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); ?>

Vedere anche:

px_delete()

px_open_fp()

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

fopen()

The example at px_new()

px_put_record

(PECL)

px_put_record -- Stores record into paradox database

Descrizione

bool px_put_record ( resource pxdoc, array record )

Stores a record into a paradox database. The record is added at the end of the database.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

px_set_blob_file

(PECL)

px_set_blob_file -- Sets the file where blobs are read from

Descrizione

bool px_set_blob_file ( resource pxdoc, string filename )

Sets the name of the file where blobs are going to be read from. Without calling this function, px_get_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 this function twice will close the first blob file and open the new one.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

px_set_parameter

(PECL)

px_set_parameter -- Sets a parameter

Descrizione

bool px_set_parameter ( resource pxdoc, string name, string value )

Sets various parameters.

Elenco dei parametri

pxdoc

name

name can 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 being recode into the targetencoding.
inputencoding: The encoding of the input data which is to be stored into the database.

value

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

px_get_info() to determine the DOS code page.

px_set_tablename

(PECL)

px_set_tablename -- Sets the name of a table (deprecated)

Descrizione

void px_set_tablename ( resource pxdoc, string name )

Sets the table name of a paradox database, which was created with px_create_fp(). Applying this function on an existing database has no effect.

Valori restituiti

Returns NULL on success or FALSE on failure.

px_set_targetencoding

(PECL)

px_set_targetencoding -- Sets the encoding for character fields (deprecated)

Descrizione

bool px_set_targetencoding ( resource 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.

See also px_get_info() to determine the DOS code page.

Valori restituiti

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.

px_set_value

(PECL)

px_set_value -- Sets a value

Descrizione

bool px_set_value ( resource pxdoc, string name, float value )

Sets various values.

Elenco dei parametri

pxdoc

name

name can be one of the following.

numprimkeys: The number of primary keys. Paradox databases always use the first numprimkeys fields for the primary index.

value

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

px_timestamp2string

(PECL)

px_timestamp2string -- Converts the timestamp into a string.

Descrizione

string px_timestamp2string ( resource pxdoc, float value, string format )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Elenco dei parametri

pxdoc
value
format

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

CVI. Parsekit Functions

Introduzione

These functions allow runtime analysis of opcodes compiled from PHP scripts.

Installazione

This PECL extension is not bundled with PHP.

Additional information such as new releases, downloads, source files, maintainer information, and a CHANGELOG, can be located here: http://pecl.php.net/package/parsekit.

You may download this PECL extension DLL from the PHP Downloads page or at http://snaps.php.net/.

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

PARSEKIT_QUIET (int): Return full detail, but without unnecessary NULL extries.
PARSEKIT_SIMPLE (int): Return shorthand opcode notation.
PARSEKIT_EXTENDED_VALUE (int): Opnode Flag
PARSEKIT_RESULT_CONST (int): Opnode Flag
PARSEKIT_RESULT_EA_TYPE (int): Opnode Flag
PARSEKIT_RESULT_JMP_ADDR (int): Opnode Flag
PARSEKIT_RESULT_OPARRAY (int): Opnode Flag
PARSEKIT_RESULT_OPLINE (int): Opnode Flag
PARSEKIT_RESULT_VAR (int): Opnode Flag
PARSEKIT_USAGE_UNKNOWN (int): Opnode Flag
PARSEKIT_ZEND_INTERNAL_CLASS (int): Class Type
PARSEKIT_ZEND_USER_CLASS (int): Class Type
PARSEKIT_ZEND_EVAL_CODE (int): Function Type
PARSEKIT_ZEND_INTERNAL_FUNCTION (int): Function Type
PARSEKIT_ZEND_OVERLOADED_FUNCTION (int): Function Type
PARSEKIT_ZEND_OVERLOADED_FUNCTION_TEMPORARY (int) PHP >= 5.0.0: Function Type
PARSEKIT_ZEND_USER_FUNCTION (int): Function Type
PARSEKIT_IS_CONST (int): Node Type
PARSEKIT_IS_TMP_VAR (int): Node Type
PARSEKIT_IS_UNUSED (int): Node Type
PARSEKIT_IS_VAR (int): Node Type
PARSEKIT_ZEND_ADD (int): Opcode
PARSEKIT_ZEND_ADD_ARRAY_ELEMENT (int): Opcode
PARSEKIT_ZEND_ADD_CHAR (int): Opcode
PARSEKIT_ZEND_ADD_INTERFACE (int) PHP >= 5.0.0: Opcode
PARSEKIT_ZEND_ADD_STRING (int): Opcode
PARSEKIT_ZEND_ADD_VAR (int): Opcode
PARSEKIT_ZEND_ASSIGN (int): Opcode
PARSEKIT_ZEND_ASSIGN_ADD (int): Opcode
PARSEKIT_ZEND_ASSIGN_BW_AND (int): Opcode
PARSEKIT_ZEND_ASSIGN_BW_OR (int): Opcode
PARSEKIT_ZEND_ASSIGN_BW_XOR (int): Opcode
PARSEKIT_ZEND_ASSIGN_CONCAT (int): Opcode
PARSEKIT_ZEND_ASSIGN_DIM (int) PHP >= 5.0.0: Opcode
PARSEKIT_ZEND_ASSIGN_DIV (int): Opcode
PARSEKIT_ZEND_ASSIGN_MOD (int): Opcode
PARSEKIT_ZEND_ASSIGN_MUL (int): Opcode
PARSEKIT_ZEND_ASSIGN_OBJ (int) PHP >= 5.0.0: Opcode
PARSEKIT_ZEND_ASSIGN_REF (int): Opcode
PARSEKIT_ZEND_ASSIGN_SL (int): Opcode
PARSEKIT_ZEND_ASSIGN_SR (int): Opcode
PARSEKIT_ZEND_ASSIGN_SUB (int): Opcode
PARSEKIT_ZEND_BEGIN_SILENCE (int): Opcode
PARSEKIT_ZEND_BOOL (int): Opcode
PARSEKIT_ZEND_BOOL_NOT (int): Opcode
PARSEKIT_ZEND_BOOL_XOR (int): Opcode
PARSEKIT_ZEND_BRK (int): Opcode
PARSEKIT_ZEND_BW_AND (int): Opcode
PARSEKIT_ZEND_BW_NOT (int): Opcode
PARSEKIT_ZEND_BW_OR (int): Opcode
PARSEKIT_ZEND_BW_XOR (int): Opcode
PARSEKIT_ZEND_CASE (int): Opcode
PARSEKIT_ZEND_CAST (int): Opcode
PARSEKIT_ZEND_CATCH (int) PHP >= 5.0.0: Opcode
PARSEKIT_ZEND_CLONE (int) PHP >= 5.0.0: Opcode
PARSEKIT_ZEND_CONCAT (int): Opcode
PARSEKIT_ZEND_CONT (int): Opcode
PARSEKIT_ZEND_DECLARE_CLASS (int) PHP >= 5.0.0: Opcode
PARSEKIT_ZEND_DECLARE_FUNCTION (int) PHP >= 5.0.0: Opcode
PARSEKIT_ZEND_DECLARE_INHERITED_CLASS (int) PHP >= 5.0.0: Opcode
PARSEKIT_ZEND_DIV (int): Opcode
PARSEKIT_ZEND_DO_FCALL (int): Opcode
PARSEKIT_ZEND_DO_FCALL_BY_NAME (int): Opcode
PARSEKIT_ZEND_ECHO (int): Opcode
PARSEKIT_ZEND_END_SILENCE (int): Opcode
PARSEKIT_ZEND_EXIT (int): Opcode
PARSEKIT_ZEND_EXT_FCALL_BEGIN (int): Opcode
PARSEKIT_ZEND_EXT_FCALL_END (int): Opcode
PARSEKIT_ZEND_EXT_NOP (int): Opcode
PARSEKIT_ZEND_EXT_STMT (int): Opcode
PARSEKIT_ZEND_FETCH_CLASS (int) PHP >= 5.0.0: Opcode
PARSEKIT_ZEND_FETCH_CONSTANT (int): Opcode
PARSEKIT_ZEND_FETCH_DIM_FUNC_ARG (int): Opcode
PARSEKIT_ZEND_FETCH_DIM_IS (int): Opcode
PARSEKIT_ZEND_FETCH_DIM_R (int): Opcode
PARSEKIT_ZEND_FETCH_DIM_RW (int): Opcode
PARSEKIT_ZEND_FETCH_DIM_TMP_VAR (int): Opcode
PARSEKIT_ZEND_FETCH_DIM_UNSET (int): Opcode
PARSEKIT_ZEND_FETCH_DIM_W (int): Opcode
PARSEKIT_ZEND_FETCH_FUNC_ARG (int): Opcode
PARSEKIT_ZEND_FETCH_IS (int): Opcode
PARSEKIT_ZEND_FETCH_OBJ_FUNC_ARG (int): Opcode
PARSEKIT_ZEND_FETCH_OBJ_IS (int): Opcode
PARSEKIT_ZEND_FETCH_OBJ_R (int): Opcode
PARSEKIT_ZEND_FETCH_OBJ_RW (int): Opcode
PARSEKIT_ZEND_FETCH_OBJ_UNSET (int): Opcode
PARSEKIT_ZEND_FETCH_OBJ_W (int): Opcode
PARSEKIT_ZEND_FETCH_R (int): Opcode
PARSEKIT_ZEND_FETCH_RW (int): Opcode
PARSEKIT_ZEND_FETCH_UNSET (int): Opcode
PARSEKIT_ZEND_FETCH_W (int): Opcode
PARSEKIT_ZEND_FE_FETCH (int): Opcode
PARSEKIT_ZEND_FE_RESET (int): Opcode
PARSEKIT_ZEND_FREE (int): Opcode
PARSEKIT_ZEND_HANDLE_EXCEPTION (int) PHP >= 5.0.0: Opcode
PARSEKIT_ZEND_IMPORT_CLASS (int) PHP >= 5.0.0: Opcode
PARSEKIT_ZEND_IMPORT_CONST (int) PHP >= 5.0.0: Opcode
PARSEKIT_ZEND_IMPORT_FUNCTION (int) PHP >= 5.0.0: Opcode
PARSEKIT_ZEND_INCLUDE_OR_EVAL (int): Opcode
PARSEKIT_ZEND_INIT_ARRAY (int): Opcode
PARSEKIT_ZEND_INIT_CTOR_CALL (int) PHP >= 5.0.0: Opcode
PARSEKIT_ZEND_INIT_FCALL_BY_NAME (int): Opcode
PARSEKIT_ZEND_INIT_METHOD_CALL (int) PHP >= 5.0.0: Opcode
PARSEKIT_ZEND_INIT_STATIC_METHOD_CALL (int) PHP >= 5.0.0: Opcode
PARSEKIT_ZEND_INIT_STRING (int): Opcode
PARSEKIT_ZEND_INSTANCEOF (int) PHP >= 5.0.0: Opcode
PARSEKIT_ZEND_ISSET_ISEMPTY (int) PHP < 5.0.0: Opcode
PARSEKIT_ZEND_ISSET_ISEMPTY_DIM_OBJ (int) PHP >= 5.0.0: Opcode
PARSEKIT_ZEND_ISSET_ISEMPTY_PROP_OBJ (int) PHP >= 5.0.0: Opcode
PARSEKIT_ZEND_ISSET_ISEMPTY_VAR (int) PHP >= 5.0.0: Opcode
PARSEKIT_ZEND_IS_EQUAL (int): Opcode
PARSEKIT_ZEND_IS_IDENTICAL (int): Opcode
PARSEKIT_ZEND_IS_NOT_EQUAL (int): Opcode
PARSEKIT_ZEND_IS_NOT_IDENTICAL (int): Opcode
PARSEKIT_ZEND_IS_SMALLER (int): Opcode
PARSEKIT_ZEND_IS_SMALLER_OR_EQUAL (int): Opcode
PARSEKIT_ZEND_JMP (int): Opcode
PARSEKIT_ZEND_JMPNZ (int): Opcode
PARSEKIT_ZEND_JMPNZ_EX (int): Opcode
PARSEKIT_ZEND_JMPZ (int): Opcode
PARSEKIT_ZEND_JMPZNZ (int): Opcode
PARSEKIT_ZEND_JMPZ_EX (int): Opcode
PARSEKIT_ZEND_JMP_NO_CTOR (int): Opcode
PARSEKIT_ZEND_MOD (int): Opcode
PARSEKIT_ZEND_MUL (int): Opcode
PARSEKIT_ZEND_NEW (int): Opcode
PARSEKIT_ZEND_NOP (int): Opcode
PARSEKIT_ZEND_OP_DATA (int) PHP >= 5.0.0: Opcode
PARSEKIT_ZEND_POST_DEC (int): Opcode
PARSEKIT_ZEND_POST_DEC_OBJ (int) PHP >= 5.0.0: Opcode
PARSEKIT_ZEND_POST_INC (int): Opcode
PARSEKIT_ZEND_POST_INC_OBJ (int) PHP >= 5.0.0: Opcode
PARSEKIT_ZEND_PRE_DEC (int): Opcode
PARSEKIT_ZEND_PRE_DEC_OBJ (int) PHP >= 5.0.0: Opcode
PARSEKIT_ZEND_PRE_INC (int): Opcode
PARSEKIT_ZEND_PRE_INC_OBJ (int) PHP >= 5.0.0: Opcode
PARSEKIT_ZEND_PRINT (int): Opcode
PARSEKIT_ZEND_QM_ASSIGN (int): Opcode
PARSEKIT_ZEND_RAISE_ABSTRACT_ERROR (int) PHP >= 5.0.0: Opcode
PARSEKIT_ZEND_RECV (int): Opcode
PARSEKIT_ZEND_RECV_INIT (int): Opcode
PARSEKIT_ZEND_RETURN (int): Opcode
PARSEKIT_ZEND_SEND_REF (int): Opcode
PARSEKIT_ZEND_SEND_VAL (int): Opcode
PARSEKIT_ZEND_SEND_VAR (int): Opcode
PARSEKIT_ZEND_SEND_VAR_NO_REF (int): Opcode
PARSEKIT_ZEND_SL (int): Opcode
PARSEKIT_ZEND_SR (int): Opcode
PARSEKIT_ZEND_SUB (int): Opcode
PARSEKIT_ZEND_SWITCH_FREE (int): Opcode
PARSEKIT_ZEND_THROW (int) PHP >= 5.0.0: Opcode
PARSEKIT_ZEND_TICKS (int): Opcode
PARSEKIT_ZEND_UNSET_DIM_OBJ (int): Opcode
PARSEKIT_ZEND_UNSET_VAR (int): Opcode
PARSEKIT_ZEND_VERIFY_ABSTRACT_CLASS (int) PHP >= 5.0.0: Opcode

Sommario
parsekit_compile_file -- Compile a string of PHP code and return the resulting op array
parsekit_compile_string -- Compile a string of PHP code and return the resulting op array
parsekit_func_arginfo -- Return information regarding function argument(s)

parsekit_compile_file

(PECL)

parsekit_compile_file -- Compile a string of PHP code and return the resulting op array

Descrizione

array parsekit_compile_file ( string filename [, array &errors [, int options]] )

Avvertimento

Elenco dei parametri

filename: A string containing the name of the file to compile. Similar to the argument to include().
errors: A 2D hash of errors (including fatal errors) encountered during compilation. Returned by reference.
options: One of either PARSEKIT_QUIET or PARSEKIT_SIMPLE. To produce varying degrees of verbosity in the returned output.

Valori restituiti

Returns a complex multi-layer array structure as detailed below.

Esempi

Esempio 1. parsekit_compile_file() example
<?php var_dump(parsekit_compile_file('hello_world.php', $errors, PARSEKIT_SIMPLE)); ?>
Il precedente esempio visualizzerà:
array(5) { [0]=> string(37) "ZEND_ECHO UNUSED 'Hello World' UNUSED" [1]=> string(30) "ZEND_RETURN UNUSED NULL UNUSED" [2]=> string(42) "ZEND_HANDLE_EXCEPTION UNUSED UNUSED UNUSED" ["function_table"]=> NULL ["class_table"]=> NULL }

Vedere anche:

parsekit_compile_string

(PECL)

parsekit_compile_string -- Compile a string of PHP code and return the resulting op array

Descrizione

array parsekit_compile_string ( string phpcode [, array &errors [, int options]] )

Avvertimento

Elenco dei parametri

phpcode: A string containing phpcode. Similar to the argument to eval().
errors: A 2D hash of errors (including fatal errors) encountered during compilation. Returned by reference.
options: One of either PARSEKIT_QUIET or PARSEKIT_SIMPLE. To produce varying degrees of verbosity in the returned output.

Valori restituiti

Returns a complex multi-layer array structure as detailed below.

Esempi

Esempio 1. parsekit_compile_string() example
<?php $ops = parsekit_compile_string(' echo "Foo\n"; ', $errors, PARSEKIT_QUIET); var_dump($ops); ?>
Il precedente esempio visualizzerà:
array(20) { ["type"]=> int(4) ["type_name"]=> string(14) "ZEND_EVAL_CODE" ["fn_flags"]=> int(0) ["num_args"]=> int(0) ["required_num_args"]=> int(0) ["pass_rest_by_reference"]=> bool(false) ["uses_this"]=> bool(false) ["line_start"]=> int(0) ["line_end"]=> int(0) ["return_reference"]=> bool(false) ["refcount"]=> int(1) ["last"]=> int(3) ["size"]=> int(3) ["T"]=> int(0) ["last_brk_cont"]=> int(0) ["current_brk_cont"]=> int(-1) ["backpatch_count"]=> int(0) ["done_pass_two"]=> bool(true) ["filename"]=> string(17) "Parsekit Compiler" ["opcodes"]=> array(3) { [8594800]=> array(5) { ["opcode"]=> int(40) ["opcode_name"]=> string(9) "ZEND_ECHO" ["flags"]=> int(768) ["op1"]=> array(3) { ["type"]=> int(1) ["type_name"]=> string(8) "IS_CONST" ["constant"]=> &string(4) "Foo " } ["lineno"]=> int(2) } ["859484C"]=> array(6) { ["opcode"]=> int(62) ["opcode_name"]=> string(11) "ZEND_RETURN" ["flags"]=> int(16777984) ["op1"]=> array(3) { ["type"]=> int(1) ["type_name"]=> string(8) "IS_CONST" ["constant"]=> &NULL } ["extended_value"]=> int(0) ["lineno"]=> int(3) } [8594898]=> array(4) { ["opcode"]=> int(149) ["opcode_name"]=> string(21) "ZEND_HANDLE_EXCEPTION" ["flags"]=> int(0) ["lineno"]=> int(3) } } }

Vedere anche:

parsekit_compile_file()

parsekit_func_arginfo

(PECL)

parsekit_func_arginfo -- Return information regarding function argument(s)

Descrizione

array parsekit_func_arginfo ( mixed function )

Avvertimento

Elenco dei parametri

function: A string describing a function, or an array describing a class/method.

Valori restituiti

Returns an array containing argument information.

Esempi

Esempio 1. parsekit_func_arginfo() example
<?php function foo($bar, stdClass $baz, &$bomb, $bling = false) { } var_dump(parsekit_func_arginfo('foo')); ?>
Il precedente esempio visualizzerà:
array(4) { [0]=> array(3) { ["name"]=> string(3) "bar" ["allow_null"]=> bool(true) ["pass_by_reference"]=> bool(false) } [1]=> array(4) { ["name"]=> string(3) "baz" ["class_name"]=> string(8) "stdClass" ["allow_null"]=> bool(false) ["pass_by_reference"]=> bool(false) } [2]=> array(3) { ["name"]=> string(4) "bomb" ["allow_null"]=> bool(true) ["pass_by_reference"]=> bool(true) } [3]=> array(3) { ["name"]=> string(5) "bling" ["allow_null"]=> bool(true) ["pass_by_reference"]=> bool(false) } }

CVII. Process Control Functions

Introduzione

Process Control support in PHP implements the Unix style of process creation, program execution, signal handling and process termination. Process Control should not be enabled within a webserver environment and unexpected results may happen if any Process Control functions are used within a webserver environment.

This documentation is intended to explain the general usage of each of the Process Control functions. For detailed information about Unix process control you are encouraged to consult your systems documentation including fork(2), waitpid(2) and signal(2) or a comprehensive reference such as Advanced Programming in the UNIX Environment by W. Richard Stevens (Addison-Wesley).

PCNTL now uses ticks as the signal handle callback mechanism, which is much faster than the previous mechanism. This change follows the same semantics as using "user ticks". You use the declare() statement to specify the locations in your program where callbacks are allowed to occur. This allows you to minimize the overhead of handling asynchronous events. In the past, compiling PHP with pcntl enabled would always incur this overhead, whether or not your script actually used pcntl.

There is one adjustment that all pcntl scripts prior to PHP 4.3.0 must make for them to work which is to either to use declare() on a section where you wish to allow callbacks or to just enable it across the entire script using the new global syntax of declare().

Nota: Questo modulo non è disponibile su piattaforme Windows.

Requisiti

Non sono necessarie librerie esterne per utilizzare questo modulo.

Installazione

Process Control support in PHP is not enabled by default. You have to compile the CGI or CLI version of PHP with --enable-pcntl configuration option when compiling PHP to enable Process Control support.

Nota: Currently, this module will not function on non-Unix platforms (Windows).

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

The following list of signals are supported by the Process Control functions. Please see your systems signal(7) man page for details of the default behavior of these signals.

WNOHANG (integer)
WUNTRACED (integer)
SIG_IGN (integer)
SIG_DFL (integer)
SIG_ERR (integer)
SIGHUP (integer)
SIGINT (integer)
SIGQUIT (integer)
SIGILL (integer)
SIGTRAP (integer)
SIGABRT (integer)
SIGIOT (integer)
SIGBUS (integer)
SIGFPE (integer)
SIGKILL (integer)
SIGUSR1 (integer)
SIGSEGV (integer)
SIGUSR2 (integer)
SIGPIPE (integer)
SIGALRM (integer)
SIGTERM (integer)
SIGSTKFLT (integer)
SIGCLD (integer)
SIGCHLD (integer)
SIGCONT (integer)
SIGSTOP (integer)
SIGTSTP (integer)
SIGTTIN (integer)
SIGTTOU (integer)
SIGURG (integer)
SIGXCPU (integer)
SIGXFSZ (integer)
SIGVTALRM (integer)
SIGPROF (integer)
SIGWINCH (integer)
SIGPOLL (integer)
SIGIO (integer)
SIGPWR (integer)
SIGSYS (integer)
SIGBABY (integer)

Esempi

This example forks off a daemon process with a signal handler.

Esempio 1. Process Control Example

<?php
declare(ticks=1);

$pid = pcntl_fork();
if ($pid == -1) {
     die("could not fork"); 
} else if ($pid) {
     exit(); // we are the parent 
} else {
     // we are the child
}

// detatch from the controlling terminal
if (!posix_setsid()) {
    die("could not detach from terminal");
}

// loop forever performing tasks
while (1) {

    // do something interesting here

}

function sig_handler($signo) 
{

     switch ($signo) {
         case SIGTERM:
             // handle shutdown tasks
             exit;
             break;
         case SIGHUP:
             // handle restart tasks
             break;
         default:
             // handle all other signals
     }

}

// setup signal handlers
pcntl_signal(SIGTERM, "sig_handler");
pcntl_signal(SIGHUP, "sig_handler");

?>

Vedere anche:

A look at the section about POSIX functions may be useful.

Sommario
pcntl_alarm -- Set an alarm clock for delivery of a signal
pcntl_exec -- Executes specified program in current process space
pcntl_fork -- Forks the currently running process
pcntl_getpriority -- Get the priority of any process
pcntl_setpriority -- Change the priority of any process
pcntl_signal -- Installs a signal handler
pcntl_wait -- Waits on or returns the status of a forked child
pcntl_waitpid -- Waits on or returns the status of a forked child
pcntl_wexitstatus -- Returns the return code of a terminated child
pcntl_wifexited -- Returns TRUE if status code represents a successful exit
pcntl_wifsignaled -- Returns TRUE if status code represents a termination due to a signal
pcntl_wifstopped -- Returns TRUE if child process is currently stopped
pcntl_wstopsig -- Returns the signal which caused the child to stop
pcntl_wtermsig -- Returns the signal which caused the child to terminate

pcntl_alarm

(PHP 4 >= 4.3.0, PHP 5)

pcntl_alarm -- Set an alarm clock for delivery of a signal

Description

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Nota: The optional restart_syscalls parameter became available in PHP 4.3.0.

Nota: The ability to use an object method as a callback became available in PHP 4.3.0. Note that when you set a handler to an object method, that object's reference count is increased which makes it persist until you either change the handler to something else, or your script ends.

Esempio 1. pcntl_signal() example

<?php
// tick use required as of PHP 4.3.0
declare(ticks = 1);

// signal handler function
function sig_handler($signo) 
{

     switch ($signo) {
         case SIGTERM:
             // handle shutdown tasks
             exit;
             break;
         case SIGHUP:
             // handle restart tasks
             break;
         case SIGUSR1:
             echo "Caught SIGUSR1...\n";
             break;
         default:
             // handle all other signals
     }

}

echo "Installing signal handler...\n";

// setup signal handlers
pcntl_signal(SIGTERM, "sig_handler");
pcntl_signal(SIGHUP,  "sig_handler");
pcntl_signal(SIGUSR1, "sig_handler");

// or use an object, available as of PHP 4.3.0
// pcntl_signal(SIGUSR1, array($obj, "do_something");

echo"Generating signal SIGTERM to self...\n";

// send SIGUSR1 to current process id
posix_kill(posix_getpid(), SIGUSR1);

echo "Done\n"

?>

Nota: As of PHP 4.3.0 PCNTL uses ticks as the signal handle callback mechanism, which is much faster than the previous mechanism. This change follows the same semantics as using "user ticks". You must use the declare() statement to specify the locations in your program where callbacks are allowed to occur for the signal handler to function properly (as used in the above example).

pcntl_wait

(PHP 5)

pcntl_wait -- Waits on or returns the status of a forked child

Description

int pcntl_wait ( int &status [, int options] )

The wait function suspends execution of the current process until a child has exited, or until a signal is delivered whose action is to terminate the current process or to call a signal handling function. If a child has already exited by the time of the call (a so-called "zombie" process), the function returns immediately. Any system resources used by the child are freed. Please see your system's wait(2) man page for specific details as to how wait works on your system.

pcntl_wait() returns the process ID of the child which exited, -1 on error or zero if WNOHANG was provided as an option (on wait3-available systems) and no child was available.

If wait3 is available on your system (mostly BSD-style systems), you can provide the optional options parameter. If this parameter is not provided, wait will be used for the system call. If wait3 is not available, providing a value for options will have no effect. The value of options is the value of zero or more of the following two constants OR'ed together:

Tabella 1. Possible values for options if wait3 is available

`WNOHANG`	Return immediately if no child has exited.
`WUNTRACED`	Return for children which are stopped, and whose status has not been reported.

pcntl_wait() will store status information in the status parameter which can be evaluated using the following functions: pcntl_wifexited(), pcntl_wifstopped(), pcntl_wifsignaled(), pcntl_wexitstatus(), pcntl_wtermsig() and pcntl_wstopsig().

Nota: This function is equivalent to calling pcntl_waitpid() with a -1 pid and no options.

pcntl_waitpid

(PHP 4 >= 4.1.0, PHP 5)

pcntl_waitpid -- Waits on or returns the status of a forked child

Description

int pcntl_waitpid ( int pid, int &status [, int options] )

The pcntl_waitpid() function suspends execution of the current process until a child as specified by the pid argument has exited, or until a signal is delivered whose action is to terminate the current process or to call a signal handling function. If a child as requested by pid has already exited by the time of the call (a so-called "zombie" process), the function returns immediately. Any system resources used by the child are freed. Please see your system's waitpid(2) man page for specific details as to how waitpid works on your system.

pcntl_waitpid() returns the process ID of the child which exited, -1 on error or zero if WNOHANG was used and no child was available

The value of pid can be one of the following:

Tabella 1. possible values for pid

`< -1`	wait for any child process whose process group ID is equal to the absolute value of `pid`.
`-1`	wait for any child process; this is the same behaviour that the wait function exhibits.
`0`	wait for any child process whose process group ID is equal to that of the calling process.
`> 0`	wait for the child whose process ID is equal to the value of `pid`.

Nota: Specifying -1 as the pid is equivalent to the functionality pcntl_wait() provides (minus options).

pcntl_waitpid() will store status information in the status parameter which can be evaluated using the following functions: pcntl_wifexited(), pcntl_wifstopped(), pcntl_wifsignaled(), pcntl_wexitstatus(), pcntl_wtermsig() and pcntl_wstopsig().

The value of options is the value of zero or more of the following two global constants OR'ed together:

Tabella 2. possible values for options

`WNOHANG`	return immediately if no child has exited.
`WUNTRACED`	return for children which are stopped, and whose status has not been reported.

CVIII. Funzioni per le espressioni regolari (Perl compatibili)

Introduzione

La sintassi utilizzata dalle espressioni regolari di queste funzioni ricorda da vicino Perl. Le espressioni regolari devono essere racchiuse tra delimitatori, ad esempio /. Ogni carattere che non sia alfanumerico od il backslash (\) può essere usato come delimitatore. Se il carattere usato come delimitatore deve essere utilizzato all'interno dell'espressione, questo deve essere preceduto dal carattere di escape (\). Infine, a partire dalla versione 4.0.4 di PHP, si possono anche usare i delimitatori stile Perl come (), {}, [], ed <>. Per maggiori dettagli vedere Sintassi dei criteri di riconoscimento.

Il delimitatore finale può essere seguito da vari modificatori che agiscono sul criterio di riconoscimento. Per maggiori informazioni si rimanda al capitolo Modificatori di criterio (Pattern Modifiers).

Utilizzando le funzioni POSIX-esteso il PHP è in grado di supportare le espressioni regolari scritte con la sintassi POSIX-esteso.

Avvertimento

Occorre prestare attenzione ad alcune limitazioni di PCRE. Maggiori informazioni in merito possono essere reperite alla pagina http://www.pcre.org/pcre.txt for more info.

Requisiti

Il supporto delle espressioni regolari è ottenuto mediante la libreria PCRE, che è un software open source, scritto da Philip Hazel, ed il cui copyright è detenuto dalla Università di Cambridge, Inghilterra. La libreria è disponibile all'indirizzo ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/.

Installazione

A partire dalla versione 4.2.0 di PHP queste funzioni sono abilitate per default. Queste funzioni possono essere disattivate usando --without-pcre-regex. Utilizzare --with-pcre-regex=DIR per specificare la directory DIR in cui sono posizionati i file di include e le librerie di PCRE, nel caso non si desideri utilizzare le librerie incluse. Nelle vecchie versioni di PHP, occorre configurare e compilare il PHP con --with-pcre-regex[=DIR] per attivare queste funzioni.

La versione per Windows di PHP ha già compilato il supporto per questo modulo. Non occorre caricare alcun modulo addizionale per potere utilizzare queste funzioni.

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

Tabella 1. Costanti di PREG

costante	descrizione
PREG_PATTERN_ORDER	Ordina i risultati in modo tale che $matches[0] sia l'array di tutti i testi riconosciuti, $matches[1] sia l'array delle stringhe identificate dal primo criterio posto tra parentesi, e così via. Questa costante si usa solo con preg_match_all().
PREG_SET_ORDER	Ordina i risultati in modo tale che $matches[0] sia l'array del primo set di testi riconosciuti, $matches[1] sia l'array del secondo set, e così via. Questa costante si usa solo con preg_match_all().
PREG_OFFSET_CAPTURE	Vedere la descrizione di `PREG_SPLIT_OFFSET_CAPTURE`. Questa costante è disponibile a partire dalla versione 4.3.0 di PHP.
PREG_SPLIT_NO_EMPTY	Questa costante indica a preg_split() di restituire solo segmenti non vuoti.
PREG_SPLIT_DELIM_CAPTURE	Questa costante indica a preg_split() di catturare le espressioni tra parentesi nel criterio di delimitazione. Questa costante è disponibile a partire dalla versione 4.0.5 di PHP.
PREG_SPLIT_OFFSET_CAPTURE	Se viene impostato questo flag, per ogni testo riconosciuto viene restituito l'offset nella stringa di ricerca. Occorre notare che questo cambia il tipo di valore restituito nell'array, ogni elemento è, a sua volta, un'array composto dalla stringa riconosciuta, all'indice 0, e dall'offset della stringa nell'indice 1. Questa costante è disponibile a partire dalla versione 4.3.0 di PHP e si utilizza solo nella funzione preg_split().

Esempi

Esempio 1. Esempi di espressioni di riconoscimento valide
/<\/\w+>/
|(\d{3})-\d+|Sm
/^(?i)php[34]/
{^\s+(\s+)?$}

Esempio 2. Esempi di espressioni errate
/href='(.*)' - manca il delimitatore finale
/\w+\s*\w+/J - il modificatore 'J' è sconosciuto
1-\d3-\d3-\d4| - manca il delimitatore iniziale

Sommario
Modificatori di criterio (Pattern Modifiers) -- Questo capitolo descrive i possibili modificatori applicabili ad una espressione regolare
Sintassi delle espressioni regolari -- Descrizione della sintassi utilizzata da PCRE per la definizione delle espressioni regolari
preg_grep -- Restituisce una matrice degli elementi riconosciuti tramite le espressioni regolari
preg_match_all -- Esegue un riconoscimento globale con le espressioni regolari
preg_match -- Riconoscimento con espressioni regolari
preg_quote -- Inserisce il carattere di escape nei caratteri delle espressioni regolari
preg_replace_callback -- Esegue ricerche e sostituzioni con espressioni regolari usando il callback
preg_replace -- Esegue una ricerca ed una sostituzione con le espressioni regolari
preg_split -- Suddivisione di una stringa tramite le espressioni regolari

Modificatori di criterio (Pattern Modifiers)

Modificatori di criterio (Pattern Modifiers) -- Questo capitolo descrive i possibili modificatori applicabili ad una espressione regolare

Descrizione

Di seguito saranno elencati i valori attualmente previsti. I nomi posti tra parentesi si riferiscono ai corrispettivi nomi usati internamente da PCRE.

i (PCRE_CASELESS)
Se si attiva questo modificatore, l'espressione regolare viene riconosciuta senza distinguere tra le lettere maiuscole e minuscole.
m (PCRE_MULTILINE)
Per default, PCRE tratta il testo su cui fare la ricerca come una "singola linea" di caratteri (anche se in realtà può contenere diversi "a capo" (newline)). Il carattere di "inizio riga" (^) indica solamente l'inizio del testo passato. Analogamente il carattere di "fine riga" ($) indica la fine del testo o prima se vi sono dei caratteri di "a capo" (a meno che non sia attivato il modificatore D). In questo modo si comporta anche Perl.
Invece quando viene indicato questo modificatore, "inizio riga" e "fine riga" vengono identificati in base ai caratteri di "a capo" presenti nel testo (rispettivamente subito dopo e subito prima di questo carattere). Questo comportamento è equivalente al modificatore /m di Perl. Se nel testo passato non vi sono caratteri di "a capo" o non vi sono occorrenze dei caratteri ^ o $ nell'espressione regolare, l'uso di questo modificatore non ha effetto.
s (PCRE_DOTALL)
Se si attiva questo modificatore, il carattere . usato nell'espressione regolare indica tutti i possibili caratteri compreso il carattere di "a capo" (newline). Senza questo modificatore il carattere "a capo" viene escluso. Questo modificare è equivalente a /s di Perl. Una espressione regolare contenente una forma negativa, come [^a], riconosce sempre un "a capo" a prescindere da questo modificatore.
x (PCRE_EXTENDED)
Se si attiva questo modificatore, verranno ignorati gli spazi presenti nell'espressione regolare, tranne quelli preceduti dal carattere di escape (\) o posti all'interno di una classe di caratteri. Saranno, inoltre, ignorati i caratteri posti tra il simbolo # (se non è preceduto dall'escape, ed è posto al di fuori di una classe di caratteri) ed il successivo carattere di "a capo" (newline). Questo comportamento equivale al flag /x di Perl e consente di inserire dei commenti all'interno di espressioni regolari complesse. Gli spazi bianchi non devono mai comparire all'interno di sequenze speciali di caratteri, come, ad esempio, la sequenza (?( che introduce ad un criterio condizionale.
e
Se viene specificato questo modificatore, la funzione preg_replace() valuta la stringa di sostituzione come codice PHP, quindi utilizza il risultato come testo da sostituire alle stringhe cercate. Gli apici singoli e doppi sono preceduti dal backslash nei riferimenti sostituiti.
Soltanto preg_replace() utilizza questo modificatore; le altre funzioni di PCRE lo ignorano.
Nota: Questo modificatore non è disponibile in PHP 3.

A (PCRE_ANCHORED)
Se si specifica questo modificatore, si forza un 'ancoraggio' del criterio di ricerca. In pratica questo viene costretto a riconoscere il testo su cui si fa la ricerca solo dall'inizio. Questo effetto può essere ottenuto anche con particolari costruzioni dell'espressione regolare, che rappresentano gli unici modi utilizzabili in Perl per ottenere il medesimo scopo.
D (PCRE_DOLLAR_ENDONLY)
L'uso di questo modificatore forza il carattere $ dell'espressione regolare a indicare la fine della stringa oggetto della ricerca. Senza questo modificatore il carattere $ indica la posizione subito prima dell'ultimo carattere se questo è un "a capo" (ma comunque non prima di ogni altro "a capo"). Questo modificatore viene ignorato se è attivato il modificatore m. Non vi sono flag equivalenti in Perl.
S
Quando una espressione regolare è destinata ad essere utilizzata diverse volte, vale la pena dedicare del tempo ad ottimizzare la velocità di riconoscimento. L'uso di questo modificatore permette questa analisi. Al momento lo studio della velocità è significativo per i criteri di ricerca "non ancorati", cioè espressioni che non hanno un carattere di partenza fisso.
U (PCRE_UNGREEDY)
Questo modificatore inverte la "voracità" delle occorrenze, in modo da non essere voraci per default, ma lo tornano ad essere se seguiti da "?". Questo flag non è compatibile con Perl. Questo comportamento può anche essere settato dalla sequenza (?U) settaggio dei modificatori all'interno del criterio di ricerca
X (PCRE_EXTRA)
Questo modificatore attiva funzionalità addizionali di PCRE che sono incompatibili con Perl. Ogni backslash (\) posto nell'espressione regolare che non sia seguito da una lettera con significato speciale causa un errore, ciò per riservare queste sequenze a future espansioni. Per default, Perl considera il backslash (\) seguito da una lettera priva di significato speciale come un qualsiasi testo. Al momento non vi sono altre caratteristiche gestite tramite questo modificatore.
u (PCRE_UTF8)
Questo modificatore attiva funzionalità di PCRE che sono incompatibili con Perl. Le stringhe di ricerca sono considerate come UTF-8. Questo modificatore è disponibile dalla versione 4.1.0 di PHP di Unix e dalla versione 4.2.3 sulla piattaforma win32.

Sintassi delle espressioni regolari

Sintassi delle espressioni regolari -- Descrizione della sintassi utilizzata da PCRE per la definizione delle espressioni regolari

Descrizione

La libreria PCRE è costituita da una serie di funzioni che utilizzano come criterio di riconoscimento le espressioni regolari mutuando la stessa sintassi e la stessa semantica di Perl 5, a parte qualche lieve differenza descritta di seguito. L'attuale implementazione corrisponde alla versione 5.005 di Perl.

Differenze rispetto a Perl

In questo capitolo saranno descritte le differenze rispetto a Perl 5.005.

Per default, lo spazio bianco indica tutti i caratteri riconoscibili dalla funzione isspace() della libreria C, ciò non pregiudica la possibilità di compilare PCRE con un set di caratteri alternativi. Normalmente isspace() riconosce gli spazi, il salto pagina, il carattere 'a capo' (newline), il carattere carriage return, la tabulazione orizzontale e verticale. Perl 5 non riconosce nel set dei caratteri indicati dallo "spazio bianco" la tabulazione verticale. Infatti il carattere di escape \v è stato presente per diverso tempo nella documentazione di Perl, ma di fatto non viene riconosciuto. Tuttavia lo stesso carattere viene trattato come spazio bianco fino alla versione 5.002 di Perl. Nelle versioni 5.004 e 5.005 non viene riconosciuto il carattere \s.
PCRE non supporta occorrenze ripetute in espressioni che "guardano avanti". Perl lo permette, ma non nel modo a cui si possa pensare. Ad esempio, (?!a){3}, non indica che i tre caratteri successivi non debbano essere delle "a", ma indica per tre volte che il carattere successivo non debba essere una "a".
Il riconoscimento di criteri parziali che possono verificarsi all'interno di espressioni che "guardano avanti" negative sono contati, ma i loro riferimenti non sono inseriti nel vettore degli offset. Perl valorizza le sue variabili da qualsiasi criterio che sia riconosciuto prima che l'espressione regolare fallisca nel riconoscere qualcosa, ma questo solo se l'espressione che "guarda avanti" contiene almeno un ramo alternativo.
Sebbene il carattere di 0 binario sia supportato nella stringa in cui si deve svolgere la ricerca, non è ammesso nel testo dell'espressione regolare, questo perché il testo viene passato come stringa C conclusa dal carattere zero. Si può comunque utilizzare la sequenza "\\x00" per richiedere il riconoscimento dello zero binario.
Non sono supportate le seguenti sequenze di escape di Perl: \l, \u, \L, \U, \E e \Q. Infatti queste sono implementate nelle funzioni di gestione delle stringhe di Perl e non nel suo motore di riconoscimento delle espressioni regolari.
L'asserzione di Perl \G non è supportata.
Ovviamente PCRE non supporta il costrutto (?{code}).
Al momento in cui si scrive, in Perl 5.005_02 vi sono alcune particolarità riguardanti la parametrizzazione delle stringhe catturate quando parte del criterio di riconoscimento viene ripetuto. Ad esempio, il riconoscimento di "aba" con il criterio /^(a(b)?)+$/, valorizza $2 con la lettera "b", usando il testo "aabbaa" con il criterio /^(aa(bb)?)+$/ non si ha la valorizzazione di $2. Tuttavia se il criterio di riconoscimento viene variato in /^(aa(b(b))?)+$/, sia $2 che $3 vengono valorizzate. Nelle versione 5.004 di Perl, la variabile $2 viene valorizzata in entrambi i casi, come pure è TRUE in PCRE. Se in futuro Perl cambierà nella gestione anche PCRE potrà cambiare di conseguenza.
Un'altra discrepanza non ancora risolta riguarda il criterio di riconoscimento /^(a)?(?(1)a|b)+$/, che in Perl 5.005_02 riconosce la stringa "a", mentre non accade in PCRE. Tuttavia in entrambi ( Perl e PCRE ) il riconoscimento di "a" con il criterio /^(a)?a/ non valorizza $1.
PCRE prevede alcune estensione alla gestione delle espressioni regolari di Perl:
1. Sebbene le asserzioni che "guardano indietro" richiedano testi di lunghezza fissa, è ammesso che ciascun ramo alternativo del criterio di ricerca possa intercettare stringhe di lunghezza differente. Al contrario Perl 5.005 richiede che tutte le stringhe abbiamo la stessa lunghezza.
2. Se viene settato PCRE_DOLLAR_ENDONLY e non viene attivato PCRE_MULTILINE, il meta-carattere $ indica soltanto la fine della stringa.
3. Se si attiva PCRE_EXTRA, un carattere backslash (\) seguito da una lettera che non abbia un significato speciale genera un errore.
4. Se si attiva PCRE_UNGREEDY, si inverte la "voracità" delle occorrenze, in modo da non essere voraci per default, ma lo tornano ad essere se seguiti da "?".

Dettagli sulle espressioni regolari

Introduzione

Di seguito verrà descritta la sintassi e la semantica delle espressioni regolari così come sono supportate da PCRE. La descrizione delle espressioni regolari può essere reperita anche nei manuali di Perl e in numerosi altri libri, alcuni dei quali ricchi di esempi. Ad esempio il libro di Jeffrey Friedl intitolato "Mastering Regular Expressions", edito da O'Reilly (ISBN 1-56592-257-3), li tratta in modo dettagliato. Questa descrizione, invece, viene intesa come una documentazione di riferimento. Una espressione regolare è un criterio utilizzato per identificare parti di un testo partendo da sinistra verso destra. La maggior parte delle lettere identifica se stessa nel testo oggetto del riconoscimento. Ad esempio il banale testo La volpe veloce intercetta la parte del testo uguale all'espressione regolare.

Meta-caratteri

La potenza delle espressioni regolari deriva dalla possibilità di inserire criteri alternativi oppure ripetuti. Questi sono codificati nel criterio di ricerca tramite l'uso di meta-caratteri, lettere che non indicano se stesse, ma sono interpretate in modo particolare.

Esistono due differenti set di meta-caratteri: quelli che sono riconosciuti ovunque tranne che all'interno di parentesi quadrate, e quelli che sono riconosciuti all'interno di parentesi quadrate. I meta-caratteri che si usano all'esterno delle parentesi quadrate sono:

\: carattere di escape generico con diversi utilizzi
^: indica l'inizio del testo (o della linea in modalità multi-linea)
$: indica la fine del testo (o della linea in modalità multi-linea)
.: indica qualsiasi carattere tranne "a capo" (per default)
[: carattere di inizio della definizione di classe
]: carattere di fine della definizione di classe
|: inizio di un ramo alternativo
(: inizio di un criterio di riconoscimento parziale
): fine del criterio di riconoscimento parziale
?: estende il significato di (, oppure 0 o 1 occorrenza, oppure occorrenza minima
*: 0 o più occorrenze
+: 1 o più occorrenze
{: inizia l'intervallo minimo/massimo di occorrenze
}: termina l'intervallo minimo/massimo di occorrenze

La parte del criterio che si trova tra parentesi quadrate viene detta "classe di caratteri". In una classe di caratteri i meta-caratteri previsti sono:

\: carattere di escape generico con diversi utilizzi
^: nega la classe, ma solo se posto all'inizio
-: indica un intervallo
]: chiude la classe di caratteri

Le sezioni seguenti descriveranno l'uso di ciascuno dei meta-caratteri.

Backslash

Il carattere backslash (\) ha diversi utilizzi. Primo uso: se viene anteposto a caratteri non alfanumerici, rimuove gli eventuali significati speciali che il carattere può avere. Questo utilizzo di backslash come carattere di escape può essere svolto sia all'interno delle classi di caratteri sia all'esterno.

Ad esempio, un criterio che deve riconoscere il carattere "*" conterrà "\*". Ciò si applica indipendentemente dal carattere seguente, sia esso interpretabile come meta-carattere o meno. Nel caso in cui un carattere non alfanumerico debba identificare se stesso è opportuno farlo precedere dal "\". In particolare per identificare un backslash occorre scrivere "\\".

Se nel criterio di riconoscimento si specifica l'opzione PCRE_EXTENDED, lo spazio bianco (diversamente da quando si trova all'interno di una classe di caratteri), e i caratteri posti tra "#" e un "a capo" all'esterno di una classe di caratteri sono ignorati. Un backslash può essere usato come escape per inserire uno spazio bianco od il carattere "#" come parte del criterio di riconoscimento.

Un secondo utilizzo del backslash consiste nel codificare in modo visibile dei caratteri non visibili. Non ci sono restrizioni nella presenza di caratteri non-stampabili, a parte lo zero binario terminante la stringa dell'espressione regolare. Di seguito saranno elencate le sequenze di caratteri che è preferibile utilizzare per la loro semplicità al posto delle corrispondenti codifiche binarie.

\a: allarme, il carattere BEL (hex 07)
\cx: "control-x", dove x è un qualsiasi carattere
\e: escape (hex 1B)
\f: salto pagina (hex 0C)
\n: "a capo" (newline) (hex 0A)
\r: carriage return (hex 0D)
\t: tabulazione (hex 09)
\xhh: carattere il cui codice esadecimale è hh
\ddd: carattere il cui codice ottale è ddd, oppure riferimento all'indietro

Il preciso effetto di "\cx" è il seguente: se "x" è una lettera minuscola, viene convertita in lettera maiuscola. In pratica viene invertito il sesto bit (hex 40) del carattere. Quindi "\cz" diventa hex 1A, ma "\c{" diventa hex 3B, mentre "\c;" diventa hex 7B.

Dopo la sequenza "\x", saranno letti due numeri esadecimali (per le lettere non si distingue tra maiuscolo e minuscolo)

Dopo la sequenza "\0" saranno lette due cifre in ottale. In entrambi i casi se vi sono meno di due cifre, saranno usati i numeri presenti. Pertanto la sequenza "\0\x\07" indica 2 zeri binari seguiti dal carattere BEL. Occorre accertarsi di passare le cifre necessarie dopo lo zero iniziale se il carattere che segue può essere scambiato per una cifra in ottale.

Più complicata è la gestione del backslash seguito da una cifra diversa da 0. Al di fuori di una classe di caratteri, PCRE tratta le cifre che trova come numeri decimali. Se il numero è inferiore a 10, oppure vi sono state almeno altrettante parentesi sinistre, la sequenza viene considerata come un riferimento all'indietro. Più avanti, nella parte dei criteri parziali, sarà descritto come funzionano questi riferimenti.

All'interno di una classe di caratteri, oppure nel caso in cui il numero decimale è maggiore di 9 e non ci sono stati altrettanti criteri parziali, PCRE rilegge le prime 3 cifre seguenti il backslash in ottale e genera il carattere dagli 8 bit meno significativi del valore ottenuto. Ogni altra cifra seguente indica se stessa. Ad esempio:

\040: è un'altro modo per indicare uno spazio
\40: ha il medesimo significato dell'esempio precedente che non vi sono 40 sotto-criteri
\7: è sempre un riferimento all'indietro
\11: può essere un riferimento all'indietro o un'altro modo per indicare il carattere di tabulazione
\011: è ancora il carattere di tabulazione
\0113: il carattere di tabulazione seguito da "3"
\113: è il carattere con il codice ottale 113 (poiché non ci possono essere più di 99 riferimenti all'indietro)
\377: è un byte con tutti i bit a 1
\81: può essere un riferimento all'indietro o uno zero binario seguito da "8" e da "1"

Occorre rilevare che valori ottali maggiori di 100 non devono essere preceduti dallo zero, questo perché la libreria considera solo tre cifre.

Tutte le sequenze che definiscono il valore di un singolo byte possono essere utilizzate sia all'interno sia all'esterno delle classe di caratteri. Inoltre, all'interno delle classi di caratteri, la sequenza "\b" viene interpretata come carattere di backspace (hex 08), mentre all'esterno ha un'altro significato (come descritto più avanti).

Il terzo utilizzo possibile per il backslash consiste nello specificare il tipo di carattere:

\d: qualsiasi cifra decimale
\D: qualsiasi carattere che non sia una cifra decimale
\s: qualsiasi carattere identificato come spazio bianco
\S: qualsiasi carattere che non sia identificato come spazio bianco
\w: qualsiasi carattere che sia una "parola" (word)
\W: qualsiasi carattere che non sia una "parola" (word)

Ciascuna coppia di sequenze di escape suddivide il set completo dei caratteri in due insiemi disgiunti. Un dato carattere deve essere identificato da un solo insieme di ciascuna coppia.

I caratteri definiti "parole" sono quelle lettere o cifre o il carattere underscore (_), cioè qualsiasi carattere che possa essere parte di una "parola" in Perl. In PCRE le definizioni di lettere e cifre vengono gestite tramite le tabelle dei caratteri, che possono variare in base a specifici parametri di localizzazione (vedere il paragrafo intitolato "Supporto alle localizzazioni"). Ad esempio, nella localizzazione fr (relativa alla Francia), qualche codice carattere maggiore di 128 è utilizzato per le lettere accentate, e queste sono identificate tramite la sequenza \w.

Queste sequenze di tipi di caratteri possono apparire sia all'interno sia all'esterno delle classi di caratteri. Ciascuna di esse identifica un carattere del tipo appropriato. Se durante la fase di identificazione di un testo, si giunge al termine della stringa in cui si esegue il riconoscimento e si hanno ancora di queste sequenze da incrociare, l'operazione di identificazione fallirà perché, ovviamente, non vi sono più caratteri in cui riconoscere le suddette sequenze.

Il quarto utilizzo per il backslash riguarda la costruzione di particolari asserzioni. L'asserzione è una condizione che deve essere soddisfatta ad un certo punto del riconoscimento, senza "consumare" caratteri dalla stringa oggetto del riconoscimento. Più avanti verranno descritte asserzioni più complicate, costruite tramite l'uso di sotto-criteri di riconoscimento, per ora saranno illustrate delle semplici asserzioni costruite con il backslash:

\b: limite di una parola
\B: non limite di una parola
\A: inizio dell'oggetto di ricerca (a prescindere dalla modalità multi-linea)
\Z: fine dell'oggetto di ricerca oppure newline alla fine (a prescindere dalla modalità multi-linea)
\z: fine dell'oggetto di ricerca (a prescindere dalla modalità multi-linea)

Queste asserzioni non possono apparire all'interno di una classe di caratteri (attenzione che la sequenza "\b" all'interno di una classe di caratteri indica il carattere backspace).

Viene definito limite di una parola la posizione nella stringa oggetto della ricerca, nella quale il carattere corrente ed il carattere precedente non soddisfano la sequenza \w o la sequenza \W (ad esempio uno soddisfa la sequenza \w e l'altro carattere soddisfa la sequenza \W), oppure quella posizione, all'inizio o alla fine della stringa, nella quale rispettivamente il primo o l'ultimo carattere soddisfa la sequenza \w.

Le asserzioni \A, \Z e \z differiscono dai tradizionali caratteri "^" e "$" (descritti di seguito) per il fatto di identificare sempre l'inizio o la fine della stringa oggetto di ricerca a prescindere da quale opzione sia stata attivata. Infatti queste asserzioni non sono alterate da PCRE_MULTILINE oppure da PCRE_DOLLAR_ENDONLY. La differenza tra \Z e \z consiste nel fatto che \Z identifica sia il carattere precedente il newline posto al termine della stringa sia la fine della stringa, mentre \z identifica solo la fine.

I caratteri "^" e "$"

In condizioni normali, il carattere "^", posto all'esterno di una classe di caratteri, indica un asserzione che è vera soltanto se il punto da cui si inizia a identificare il testo si trova all'inizio della stringa oggetto della ricerca. Al contrario, se il carattere "^" si trova all'interno di una classe di caratteri, assume altri significati (vedere i capitoli seguenti).

Non è necessario che il carattere "^" sia la prima lettera del criterio di riconoscimento nei casi in cui si utilizzino dei criteri di riconoscimento alternativi. Tuttavia è necessario che sia la prima lettera nei rami alternativi in cui compare. Se si inserisce il carattere "^" in tutte le alternative, caso che ricorre quando si vuole riconoscere un testo a partire dall'inizio della stringa, si dice che si è costruito un criterio di ricerca "ancorato". (Esistono anche altre costruzioni che portano all'ancoraggio di un criterio di ricerca).

Il carattere dollaro "$" è una asserzione che è TRUE soltanto se il punto a cui si è arrivati ad identificare il testo si trova alla fine della stringa oggetto della ricerca, o nella lettera immediatamente precedente il carattere di "a capo", che (per default) è l'ultimo carattere del testo. Il dollaro "$" non deve essere necessariamente l'ultima lettera di un criterio di riconoscimento se in questo si sono utilizzati dei criteri alternativi. Deve, comunque, essere l'ultima lettera nei criteri ove compare. Il carattere dollaro "$" non ha significati speciali all'interno di una classe di caratteri.

Il comportamento del simbolo "$" può essere variato in modo da identificare la reale fine della stringa oggetto di ricerca attivando il flag PCRE_DOLLAR_ENDONLY durante la compila o durante la fase di riconoscimento. Ciò non influisce sull'asserzione \Z.

Il comportamento dei simboli "^" e "$" può essere influenzato dall'opzione PCRE_MULTILINE. Quando viene attivata, questi caratteri identificano rispettivamente, oltre ai tradizionali inizio e fine testo, la lettera immediatamente successiva ed immediatamente precedente il carattere "\n" presente all'interno della stringa oggetto di ricerca. Per esempio il criterio /^abc$/ riconosce il testo "def\nabc" solo in modalità multi-linea. Di conseguenza i criteri di riconoscimento che sono "ancorati" in modalità singola linea, non lo sono in modalità multi-linea. L'opzione PCRE_DOLLAR_ENDONLY viene ignorata se si attiva il flag PCRE_MULTILINE .

Occorre rilevare che le sequenze \A, \Z e \z possono essere utilizzate per riconoscere l'inizio e la fine del testo in entrambe le modalità, e, se tutti i criteri alternativi iniziano con \A, si ha ancora un criterio "ancorato" a prescindere che sia attivata o meno l'opzione PCRE_MULTILINE.

FULL STOP

Il carattere punto ".", all'esterno di una classe di caratteri, identifica qualsiasi carattere, anche quelli non stampabili, ma (per default) non il carattere "a capo". Invece se si abilita l'opzione PCRE_DOTALL si avrà anche il riconoscimento del carattere "a capo". La gestione del simbolo "." è svincolata dalla gestione dei simboli "^" ed "$", l'unica relazione che possono avere riguarda il carattere "a capo". Il punto "." non ha significati speciali all'interno delle classi di caratteri.

Parentesi quadrate

Un parentesi quadrata aperta "[" inizia una classe di caratteri; una parentesi quadrata chiusa "]" termina la definizione della classe. Di suo il carattere di parentesi quadrata chiusa non ha significati speciali. Se occorre inserire la parentesi chiusa all'interno di una classe di caratteri, questa deve essere la prima lettera (ovviamente deve seguire il carattere "^", se presente) oppure deve essere preceduta dal carattere di escape "\".

Una classe di caratteri identifica un singolo carattere nella stringa oggetto di ricerca; il carattere deve comparire nel set di caratteri definito dalla classe, a meno che il primo carattere della classe non sia l'accento circonflesso "^", in tal caso il carattere non deve essere nel set definito dalla classe. Se è richiesto l'inserimento del carattere "^" nel set definito dalla classe, questo non deve essere la prima lettera dopo la parentesi di apertura, oppure deve essere preceduto dal carattere di escape (\).

Ad esempio, la classe [aeiou] identifica ogni vocale minuscola, mentre [^aeiou] identifica tutti i caratteri che non siano delle vocali minuscole. Occorre notare che il simbolo "^" è un modo pratico per indicare i caratteri che sono nella classe, citando quelli che non lo sono. Questa non è una asserzione: consuma un carattere della stringa oggetto di ricerca e fallisce se ci si trova alla fine del testo.

In un riconoscimento senza distinzione tra minuscole e maiuscole, ogni lettera della classe identifica sia la versione maiuscola sia la minuscola. Così, ad esempio, la classe [aeiou] identifica sia "A" sia "a", e, in questo caso, [^aeiou] non identifica "A", mentre con la distinzione delle maiuscole [^aeiou] identifica la lettera "A".

Il carattere di "a capo" (newline) non viene trattato in modo speciale nelle classi di caratteri, indipendentemente dalle opzioni PCRE_DOTALL o PCRE_MULTILINE. La classe [^a] riconosce sempre il carattere "a capo".

Il segno meno (-) può essere usato per definire un intervallo all'interno della classe. Ad esempio, [d-m] identifica ogni lettera compresa tra d ed m inclusi. Se occorre inserire il segno meno (-) come carattere da riconoscere o lo si fa precedere dal carattere di escape (\), oppure lo si mette in una posizione tale che non possa essere identificato come definizione di un intervallo (ad esempio all'inizio o alla fine della definizione della classe).

Non è possibile usare il carattere "]" come limite di un intervallo. Un criterio definito come [W-]46], viene inteso come una classe di due caratteri (W e -) seguita dalla stringa 46], in tal modo sarebbero riconosciuti i testi "W46]" oppure "-46]". Quindi è necessario precedere la lettera "]" con il carattere di escape (\), in questo modo [W-\]46], viene interpretata correttamente come una singola classe contenente un range seguito da due caratteri separati. In alternativa, per delimitare l'intervallo si può utilizzare la notazione ottale di "]".

Gli intervalli utilizzano la sequenza di caratteri ASCII. Inoltre possono essere utilizzati per definire caratteri con specifica numerica (ad esempio [\000-\037]). Nei casi in cui si abiliti il riconoscimento senza distinzione tra lettere maiuscole e minuscole, gli intervalli comprendenti lettere identificano sia la lettera maiuscola che minuscola. Ad esempio, [W-c] è equivalente ad [][\^_`wxyzabc] (con il riconoscimento a prescindere dalla lettera maiuscole e minuscole), e, se si utilizza la tabella dei caratteri locali francesi "fr", [\xc8-\xcb] identifica la lettera "e" accentata sia maiuscola sia minuscola.

Nelle classi di caratteri si possono utilizzare le sequenze \d, \D, \s, \S, \w e \W per aggiungere altri tipi di caratteri alla classe. Ad esempio, [\dABCDEF] riconosce qualsiasi cifra esadecimale. Il carattere "^" può essere utilizzato con i caratteri maiuscoli per indicare un set di caratteri più ristretto che l'identificazione del set di caratteri minuscoli. Ad esempio, la classe [^\W_] identifica qualsiasi lettera o cifra ma non il trattino basso (_).

Tutti i caratteri non alfabetici, eccetto \, -, ^ (posto all'inizio) e ] non sono speciali per la classi di caratteri, e non sono dannosi se preceduti dal caratteri di escape (\).

Barra verticale (|)

La barra verticale (|) viene utilizzata per separare criteri di riconoscimento alternativi. Ad esempio il seguente criterio gilbert|sullivan può riconoscere "gilbert" oppure "sullivan". Ci possono essere innumerevoli alternative, compresa un'alternativa vuota (per identificare una stringa vuota). Il processo di riconoscimento prova tutte le alternative possibili (da sinistra a destra) fino a quando non ne trova una che sia soddisfatta. Se le alternative sono nella definizione di un criterio parziale il riconoscimento ha successo quando avviene su tutto il criterio.

Settaggio delle opzioni interne

Le opzioni PCRE_CASELESS, PCRE_MULTILINE , PCRE_DOTALL, PCRE_UNGREEDY e PCRE_EXTENDED possono essere cambiate "al volo" dall'interno del criterio di riconoscimento, utilizzando le sequenze di lettere definite per queste opzioni in Perl, racchiuse tra "(?" ed ")". Le lettere utilizzabili sono:

Tabella 1. Lettere per le opzioni interne

`i`	per PCRE_CASELESS
`m`	per PCRE_MULTILINE
`s`	per PCRE_DOTALL
`x`	per PCRE_EXTENDED
`U`	per PCRE_UNGREEDY

Ad esempio, (?im) abilita il riconoscimento senza distinzione tra lettere maiuscole e minuscole e la modalità multi-linea. E' anche possibile disabilitare queste opzioni facendo precedere la lettera dal segno meno (-), o combinare l'attivazione con la disattivazione come nel caso (?im-sx), in cui si attiva PCRE_CASELESS e PCRE_MULTILINE e si disattiva PCRE_DOTALL e PCRE_EXTENDED. Se la lettera compare sia prima che dopo il segno meno (-) l'opzione resta disabilitata.

L'ambito di validità delle opzioni dipende da dove sono i flag di abilitazione/disabilitazione nel criterio di ricerca. Nei casi in cui il settaggio di un'opzione avvenga all'esterno di un qualsiasi criterio parziale (come definito in seguito) gli effetti sono medesimi di quando l'attivazione/disattivazione avviene all'inizio del criterio di riconoscimento. Gli esempi seguenti si comportano tutti allo stesso modo:

       (?i)abc
       a(?i)bc
       ab(?i)c
       abc(?i)

In questi esempi si attiva PCRE_CASELESS per il criterio "abc". In altre parole, questo settaggio compiuto al primo livello si applica a tutto il criterio (a meno che non vi siano altre variazioni nelle sotto-regole di riconoscimento). Qualora vi siano più settaggi per lo stesso parametro, viene utilizzato quello più a destra.

Se si inserisce la variazione di un'opzione in una sotto-regola gli effetti sono differenti. Questa è una variazione rispetto al comportamento di Perl 5.005. Una variazione apportata all'interno di una sotto-regola, vale solo per la parte della sotto-regola che segue la variazione, pertanto (a(?i)b)c identifica abc, aBc e nessuna altra stringa ( si assume che PCRE_CASELESS non sia usato). Da ciò deriva che le opzioni possono avere comportamenti differenti nelle varie parti del criterio di riconoscimento. Ogni variazione apportata ad una ramo alternativo del criterio viene estesa alle alternative successive della medesima sotto-regola. Ad esempio, (a(?i)b|c) identifica "ab", "aB", "c" e "C", anche se per identificare "C" viene scartato il primo ramo prima di incontrare il settaggio dell'opzione. Questo accade perché gli effetti dei settaggi vengono inseriti nella fase di compila. Diversamente si avrebbero dei comportamenti molto bizzarri.

Le opzioni specifiche di PCRE PCRE_UNGREEDY e PCRE_EXTRA possono essere variate nel medesimo modo delle opzioni Perl compatibili, utilizzando rispettivamente i caratteri U e X. Il flag (?X) è particolare poiché deve comparire prima di qualsiasi opzione esso attivi anche quando si trova al primo livello. E' opportuno inserirlo all'inizio.

Sotto-regole

Le sotto-regole sono delimitate dalle parentesi tonde e possono essere annidate. La definizione di una parte di una regola di riconoscimento come sotto-regola può servire a:

1. Localizzare un set di alternative. Ad esempio nel seguente criterio di riconoscimento cat(aract|erpillar|) si riconosce una tra le parole "cat", "cataract" oppure "caterpil- lar". Se non fossero state usate le parentesi, il criterio avrebbe permesso il riconoscimento delle parole "cataract", "erpillar" oppure una stringa vuota.

2. Identificare e catturare parte del testo riconosciuto dalla sotto-regola (come illustrato in seguito). Quando il riconoscimento dell'intero criterio ha avuto successo, le porzioni della stringa oggetto della ricerca identificate dalle sotto-regole sono restituite alla funzione chiamante tramite l'argomento vettore della funzione pcre_exec(). Per determinare il numero ordinale di ciascuna sotto-regola si contano le parentesi aperte da sinistra verso destra partendo da 1.

Ad esempio, se si esegue un riconoscimento nella frase "the red king" con il seguente criterio the ((red|white) (king|queen)) si ottengono i testi "red king", "red" e "king", rispettivamente identificati dalla sotto-regola 1, 2 e 3.

Il fatto che le parentesi tonde adempiano a due funzioni non sempre porta a situazioni comprensibili. Spesso capita di dovere raggruppare delle sotto-regole senza per questo essere richiesta la cattura del testo. A tale scopo l'uso della sequenza "?:" dopo la parentesi di apertura permette di indicare che questa sotto-regola non deve catturare il testo, e non deve essere conteggiata nel numero d'ordine delle sotto-regole di cattura. Ad esempio, applicando il criterio the ((?:red|white) (king|queen)) alla frase "the white queen", si catturano i testi "white queen" e "queen", rispettivamente numerati 1 e 2. Il numero massimo di testi catturabili è 99, il numero massimo di sotto-regole, a prescindere che siano di cattura o meno, è 200.

Come utile abbreviazione, nei casi in cui l'attivazione di alcune opzioni debba essere fatta all'inizio di una sotto-regola non di cattura, la lettera dell'opzione può comparire tra la "?" e ":". Pertanto i due criteri

       (?i:saturday|sunday)
       (?:(?i)saturday|sunday)

riconoscono esattamente lo stesso set di parole. Poiché i rami alternativi sono provati da sinistra verso destra, e le opzioni non sono azzerate fino a quando non si è conclusa la sotto-regola, una opzione attivata in un ramo alternativo si applica a tutte le alternative che seguono. Pertanto, nell'esempio di prima, sia la parola "SUNDAY" che la parola "Saturday" sono testi identificati correttamente.

Ripetizioni

Le ripetizioni sono il numero delle occorrenze che possono essere indicate dopo i seguenti elementi:

un singolo carattere, possibilmente preceduto dal carattere di escape (\)
il metacarattere .
una classe di caratteri
un riferimento all'indietro (vedere la sezione successiva)
una sotto-regola (a meno che non si tratti di una asserzione - vedere più avanti)

In generale una occorrenza specifica un numero minimo e massimo di riconoscimenti previsti tramite la specifica dei due limiti, posti tra parentesi graffe e separati da una virgola. Entrambi i numeri devono essere minori di 65536 ed il primo deve essere minore o uguale rispetto al secondo. Ad esempio: z{2,4} identifica "zz", "zzz" oppure "zzzz". La parentesi graffa chiusa di suo non rappresenta un carattere speciale. Se si omette il secondo numero, ma si lascia la virgola, non si indica un limite superiore; se sia la virgola sia il secondo numero sono omessi, l'occorrenza specifica l'esatto numero di riconoscimenti richiesti. Il criterio [aeiou]{3,} identifica almeno 3 o più vocali consecutive, mentre \d{8} identifica esattamente 8 cifre. Una parentesi graffa aperta che compaia in una posizione in cui non sia prevista una occorrenza, o che comunque non sia riconducibile alla sintassi di una occorrenza, viene tratta come il carattere "{". Ad esempio {,6} non indica delle occorrenze, ma una stringa di 4 caratteri.

L'indicazione {0} è permessa. Indica di comportarsi come se l'elemento precedente all'occorrenza non fosse presente.

Per praticità (e compatibilità verso il passato) si usano 3 abbreviazioni per le occorrenze più comuni:

Tabella 2. Indicatore di occorrenza

`*`	equivale a `{0,}`
`+`	equivale a `{1,}`
`?`	equivale a `{0,1}`

E' anche possibile creare un ciclo infinito facendo seguire ad una sotto-regola che non identifica alcun carattere una occorrenza priva di limite superiore. Ad esempio: (a?)*

Le versioni precedenti di Perl e di PCRE segnalavano un errore durante la fase di compila per questi criteri. Tuttavia, poiché vi sono casi dove questi criteri possono essere utili, queste regole sono accettate, ma, se la ripetizione non riconosce alcun carattere, il ciclo viene interrotto.

Per default le occorrenze sono "bramose", infatti identificano più testi possibile (fino al numero massimo permesso), senza per questo fare fallire il riconoscimento della parte rimanente del criterio di ricerca. Il classico esempio dove questo comportamento può essere un problema, riguarda il riconoscimento dei commenti nei programmi C. Questi compaiono tra le sequenze /* ed */, ma all'interno, nel commento, si possono usare sia il carattere *, sia il carattere /. Il tentativo di individuare i commenti C con il seguente criterio /\*.*\*/ se applicato al commento /* primo commento */ nessun commento /* secondo commento */ non ha successo, perché identifica l'intera stringa a causa della "bramosia" dell'elemento ".*".

Tuttavia, se un'occorrenza è seguita da un punto interrogativo, questa cessa di essere "bramosa", e identifica il numero minimo di testi permessi. Pertanto il criterio /\*.*?\*/ si comporta correttamente con i commenti C. Il significato delle varie occorrenze non è stato cambiato, si è soltanto modificato il numero delle occorrenze da riconoscere. Attenzione a non confondere questo uso del punto interrogativo con il suo proprio significato. Dati i due utilizzi del ?, può anche capitare di averli entrambi come in \d??\d che, preferibilmente, identifica una cifra, ma può riconoscerne due se questa è l'unica via per soddisfare il riconoscimento dell'intero criterio.

Se si attiva l'opzione PCRE_UNGREEDY (un'opzione disponibile anche in Perl), per default le occorrenze non sono "bramose", ma ogni singola occorrenza può essere resa "bramosa" se seguita dal punto interrogativo. In altre parole si è invertito il normale comportamento.

Quando si indica un numero minimo di occorrenze maggiore di 1, per una sotto-regola posta tra parentesi, oppure si indica un numero massimo di occorrenze, la fase di compila richiede più spazio in proporzione ai valori minimo e massimo.

Se un criterio inizia con .* oppure .{0,} e si è attivata l'opzione PCRE_DOTALL (equivalente al /s di Perl), permettendo al . di identificare il carattere di "a capo", si dice che il criterio è implicitamente ancorato, perché qualsiasi elemento che segue sarà confrontato con ciascun carattere della stringa oggetto della ricerca, e pertanto non vi è nessuna posizione, a parte la prima, da cui ripartire per ritentare il riconoscimento dell'intero criterio. PCRE tratta tale criterio come se fosse preceduto dalla sequenza \A. Nei casi in cui è noto a priori che la stringa oggetto di ricerca non contiene caratteri di "a capo", vale la pena di attivare l'opzione PCRE_DOTALL se il criterio di ricerca inizia con ".*", per ottenere questa ottimizzazione, oppure, in alternativa, usare "^" per indicare in modo esplicito un ancoraggio.

Quando si ripete una sotto-regola di cattura, il testo estrapolato è la parte identificata dall'iterazione finale. Ad esempio se il criterio (tweedle[dume]{3}\s*)+ viene applicato al testo "tweedledum tweedledee", il testo estrapolato sarà "tweedledee". Tuttavia se vi sono delle sotto-regole annidate, il testo catturato può essere determinato dalle iterazioni precedenti. Ad esempio nel criterio /(a|(b))+/ applicato a "aba", la seconda stringa catturata è "b".

Riferimenti all'indietro

Esternamente ad una classe di caratteri, un backslah (\) seguito da una o più cifre maggiori di 0 è un riferimento all'indietro verso testi catturati precedentemente (ad esempio alla sinistra rispetto a dove ci si trova), conteggiati tramite il numero delle parentesi chiuse precedenti.

Tuttavia, se il numero che segue il backslash (\) è un valore inferiore a 10, si assume che si tratti sempre di un riferimento all'indietro, e pertanto viene generato un errore se nel criterio non vi sono almeno altrettante parentesi chiuse di sotto-regole di cattura. In altre parole per i numeri inferiori a 10 non è necessario che il numero parentesi precedenti (a sinistra) alla sotto-regola sia pari o maggiore al numero indicato. Vedere la sezione relativa al backslash per informazioni su come gestire le cifre seguenti il backslash.

Un riferimento all'indietro identifica ciò che è già stato catturato dalla sotto-regola, e non ciò che la sotto-regola stessa possa riconoscere. Ad esempio il criterio (sens|respons)e and \1ibility può riconoscere "sense and sensibility" oppure "response and responsibility", ma non il testo "sense and responsibility". Se al momento del riferimento all'indietro, è attiva la distinzione tra lettere maiuscole e minuscole, il formato della lettera diventa rilevante. Ad esempio, ((?i)rah)\s+\1 può identificare "rah rah" e "RAH RAH", ma non "RAH rah", anche se la sotto-regola originale eseguiva dei riconoscimenti a prescindere dalle lettere maiuscole e minuscole.

Nella medesima sotto-regola si possono avere più di un riferimento all'indietro. Se una sotto-regola non viene utilizzata in un particolare riconoscimento, un riferimento a questa ha sempre esito negativo. Ad esempio il criterio (a|(bc))\2 non avrà mai successo se l'identificazione della stringa inizia con "a" e non con "bc". Dato che sono possibili fino a 99 riferimenti all'indietro, tutte le cifre che seguono un backslash (\) sono considerate come parte di un potenziale numero di riferimento. Se il criterio continua con altri caratteri numerici, occorre stabilire un carattere per delimitare il numero del riferimento. Se si attiva l'opzione PCRE_EXTENDED questo carattere può essere lo spazio. Altrimenti si può usare un commento vuoto.

Un riferimento all'indietro non ha successo se viene inserito in una sotto regola prima che sia applicata. Con questo si intende, ad esempio, che (a\1) non avrà mai successo, ma, nel caso di una sottoregola ripetuta, si avrà un riscontro positivo. Ad esempio (a|b\1)+ identificherà qualsiasi numero di "a", ma anche "aba" oppure "ababaa" eccetera. In pratica a ciascuna iterazione della sotto-regola il riferimento andrà a sostituire la stringa riconosciuta tramite la sotto-regola dell'iterazione precedente. Affinchè il tutto funzioni, è necessario che la prima iterazione sia identificata senza l'ausilio del riferimento "all'indietro". Ciò può essere ottenuto o usando casi alternativi, come nell'esempio precedente, o usando le occorrenze indicando come numero minimo di occorrenze il valore zero.

Asserzioni

L'asserzione è un test basato su un carattere, che può precedere o seguire l'attuale punto di riconoscimento, e non consuma alcun carattere. Le semplici asserzioni quali \b, \B, \A, \Z, \z, ^ e $ sono state descritte precedentemente. Asserzioni più complesse possono essere strutturate come delle sotto-regole. Se ne hanno di due tipologie: quelle che "guardano avanti" alla posizione attuale nella stringa oggetto del riconoscimento, e quelle che "guardano dietro" la posizione attuale.

Una asserzione definita come sotto-regola esegue il riconoscimento nel modo usuale, ma tale riconoscimento non sposta la posizione attuale nella stringa. Le asserzioni che "guardano avanti" cominciano per "(?=", se sono positive, per "(?!", se sono asserzioni negative. Ad esempio \w+(?=;) riconosce una parola seguita da ";", ma non include il punto e virgola nel riconoscimento, mentre foo(?!bar) identifica qualsiasi occorrenza di "foo" che non sia seguita da "bar". Attenzione che il criterio, apparentemente simile, (?!foo)bar non riconosce alcuna occorrenza di "bar" se questa è preceduta da qualsiasi testo che non sia "foo"; infatti l'espressione riconosce qualsiasi occorrenza di "bar", poiché l'asserzione (?!foo) è sempre TRUE quando i tre caratteri successivi sono "bar". Pertanto è necessario una asserzione che "guarda" all'indietro per ottenere effetto desiderato.

Le asserzioni che "guardano" indietro positive iniziano con "(?<=", e con "(?<!" le negative. Ad esempio: (?<!foo)bar riconosce una occorrenza di "bar" che non sia preceduta da "foo". Le asserzioni che "guardano" indietro hanno una limitazione: tutte le stringhe che riconoscono devono avere lunghezza fissa. Mentre, se si hanno casi alternativi, la limitazione della lunghezza fissa non sussiste. Quindi (?<=bullock|donkey) è una asserzione permessa, ma (?<!dogs?|cats?) genera un errore durante la fase di compila. Rami alternativi con lunghezze di stringa differenti sono permessi solo al primo livello dell'asserzione. Questa è da considerarsi una estensione rispetto a Perl 5.005, che richiede a tutte le alternative possibili la medesima lunghezza di stringa. Quindi una asserzione tipo (?<=ab(c|de)) non è permessa, poiché il suo singolo ramo di primo livello può identificare testi di due lunghezze differenti, ma è accettabile se riscritta usando due alternative di primo livello: (?<=abc|abde) L'implementazione di questo tipo di asserzioni consiste, per ciascuna alternativa, di uno spostamento all'indietro temporaneo per la lunghezza fissa necessaria, e ad un tentativo di riconoscimento del testo. Se non ci sono sufficienti caratteri precedenti alla posizione attuale, l'asserzione è destinata a fallire. L'uso accoppiato delle asserzioni che "guardano" indietro con sotto-regole a riconoscimento singolo può essere utile per identificare la fine dei testi; un esempio è illustrato al termine della sezione sulle sotto-regole a riconoscimento singolo.

Diverse asserzioni (di qualsiasi tipologia) possono essere utilizzate in modo consecutivo. Ad esempio: (?<=\d{3})(?<!999)foo riconosce "foo" preceduto da tre cifre che non siano "999". Occorre rilevare che ciascuna asserzione viene applicata singolarmente sul medesimo punto nella stringa oggetto di riconoscimento. Nell'esempio precedente per prima cosa si verifica che i tre caratteri precedenti siano cifre, quindi che non siamo "999". Questo esempio non identifica il testo se "foo" è preceduto da sei caratteri di cui i primi tre siano cifre e i secondi tre non siano "999". In pratica il testo "123abcfoo" non viene riconosciuto. Un criterio per riconoscere tale stringa può essere: (?<=\d{3}...)(?<!999)foo

In questo caso la prima asserzione controlla i primi sei caratteri verificando che i primi tre siano cifre, mentre la seconda asserzione verifica che i secondi tre caratteri non siano "999".

Le asserzioni possono essere annidate in qualsiasi combinazione. Il seguente esempio (?<=(?<!foo)bar)baz identifica il testo "baz" se è preceduto da "bar" il quale non deve essere preceduto da "foo", mentre (?<=\d{3}...(?<!999))foo è un'altro criterio che riconosce "foo" preceduto da tre cifre e da tre caratteri che non siano "999".

Le asserzioni definite come sotto-regole non catturano parte del testo e non possono essere ripetute (non avrebbe senso ripetere il medesimo riconoscimento sul medesimo testo). Se una di queste asserzioni contiene una sotto-regola di cattura questa viene conteggiata ai fini della numerazione delle regole di cattura. Tuttavia il testo viene effettivamente catturato solo nelle asserzioni positive, dato che non avrebbe senso farlo in quelle negative.

Le asserzioni possono essere composte fino ad un massimo di 200 sotto-regole. subpatterns.

Sotto-regole a riconoscimento singolo (Once-only subpatterns)

Con l'indicazione del numero minimo e massimo di ripetizioni, il fallimento del riconoscimento della parte successiva del testo causa una ripetizione dell'identificazione con un numero di occorrenze diverse per verificare se in questa situazione anche il resto del testo viene identificato. In alcune situazioni può essere utile bloccare questo meccanismo, per la cambiata natura del criterio, oppure per fare fallire la ricerca prima di quando potrebbe accadere, oppure quando l'autore sa che non ci sono punti da cui ripartire.

Consideriamo, ad esempio, il criterio \d+foo applicato alla seguente linea 123456bar

Dopo avere identificato le 6 cifre ed avere mancato nel riconoscimento di "foo", il comportamento normale consiste nel tentare di procedere identificando 5 cifre per l'elemento \d+, quindi tentare con 4 e così via, prima di fallire definitivamente. Le sotto-regole a riconoscimento singolo permettono di specificare che, una volta riconosciuta una porzione della regola, questa non debba essere più considerata, in maniera tale da abortire immediatamente il riconoscimento se non si ha successo nell'identificare la parte restante del criterio. L'espressione per definire questo tipo di sotto-regola richiede un'altro tipologia di utilizzo speciale delle parentesi. Infatti iniziano con (?> come nell'esempio seguente: (?>\d+)bar

Questa tipologia di parentesi "inchioda" la parte di criterio una volta che avviene il riconoscimento, e, quindi, un fallimento successivo impedisce la ri-elaborazione di questo segmento. Tuttavia, occorre notare che gli elementi precedenti a questo si comportano in modo normale, e pertanto la ri-elaborazione, pur non toccando questo elemento, passa ai precedenti.

Una descrizione alternativa di questa tipologia di sotto-regola potrebbe essere che questo criterio identifica un testo come avrebbe fatto un singolo criterio se fosse stato ancorato alla posizione corrente.

Le sotto-regole a riconoscimento singolo non compiono la cattura del testo identificato. I casi semplici illustrati in precedenza possono essere considerati come una estremizzazione della ripetizione che porta ad inglobare tutto ciò che può. Pertanto, da una parte \d+ e \d+? sono sequenze che si adattano a riconoscere il numero corretto di cifre affinchè la ricerca abbia successo, dall'altra la sequenza (?>\d+) riconosce soltanto una sequenza di cifre.

Ovviamente queste costruzioni possono contenere diverse sotto-regole sia complesse, sia annidate.

Le sotto-regole a riconoscimento singolo possono essere usate congiuntamente alle asserzioni che guardano indietro, per definire una regola efficiente per riconoscere la fine della stringa. Ad esempio si consideri questo semplice criterio: abcd$ quando viene applicato ad un lungo testo può non avere successo. Questo perché il riconoscimento procede da sinistra verso destra, quindi PCRE prima cerca la "a", e poi cerca di riconoscere la parte restante del criterio. Se si modifica il criterio nel seguente modo ^.*abcd$ allora la sequenza iniziale .* in prima battuta identificherà tutto il testo, ma quando fallisce (poiché non vi sono più "a"), la ricerca tornerà indietro di uno (quindi tutto il testo tranne l'ultimo carattere), quindi, se continua non esserci la "a", si torna indietro di due, e così via. Continuando a tornare indietro alla ricerca della "a" si percorre tutto il testo da destra a sinistra, senza ottenere nulla di valido. Tuttavia se si riscrive il criterio come: ^(?>.*)(?<=abcd) non si attiva più lo scorrimento verso sinistra per .* , ma viene costretto a riconoscere tutto il testo (esito del primo tentativo). La asserzione successiva, esegue una verifica sulle ultime 4 lettere.Se fallisce, ciò avviene immediatamente, provocando un impatto sensibile nei tempi di elaborazione con testi molto lunghi.

Quando un criterio di riconoscimento contiene un elemento ripetuto senza limite all'interno di una sotto-regola che anch'essa possa ripetuta illimitatamente, l'uso delle sotto-regole a riconoscimento singolo è l'unico mezzo per evitare che certi mancati riconoscimenti richiedano molto tempo per essere rilevati. Ad esempio il criterio (\D+|<\d+>)*[!?] riconosce un numero indefinito di frammenti di testo contenenti a loro volta numeri o caratteri non numerici racchiusi tra <>, seguiti dai caratteri ! o ?. Quando il riconoscimento ha successo l'esecuzione è rapida, ma quando viene applicato al testo aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa richiede molto tempo prima di evidenziare l'errore. Questo accade perché la stringa può essere suddivisa tra i due elementi ripetuti in un elevato numero di modi che debbono essere verificati. Nell'esempio si usa [!?] piuttosto che un singolo carattere alla fine, questo perché sia Perl sia PCRE hanno una ottimizzazione che permette un veloce riconoscimento dell'errore se si usa un solo carattere. Infatti memorizzano l'ultimo carattere singolo richiesto per un riconoscimento, e, se non lo trovano nel testo, falliscono subito. Se il criterio viene modificato in ((?>\D+)|<\d+>)*[!?] le sequenze di caratteri non numerici non possono essere interrotte e pertanto il mancato riconoscimento viene rilevato più velocemente.

Sotto-regole condizionali (Conditional subpatterns)

E' possibile forzare il processo di riconoscimento a obbedire alle sotto-regole in modo condizionato, oppure a scegliere tra due alternative in base al risultato di una asserzione, o piuttosto se la sotto-regola di cattura precedente ha riconosciuto il proprio testo. I due metodi possibili per esprimere una sotto-regola condizionale sono:

       (?(condizione)yes-pattern)
       (?(condizione)yes-pattern|no-pattern)

Se la condizione è soddisfatta, si usa la regola indicata in yes-pattern, altrimenti si applica il no-pattern (qualora sia specificato). Se nella sotto-regola vi sono più di due alternative, PCRE segnala un errore in fase di compila.

Vi sono due tipi di condizioni. Se il testo tra le parentesi consiste in una sequenza di cifre, allora la condizione è soddisfatta se la sotto-regola di cattura di quel numero è stata precedentemente riconosciuta. Si consideri il seguente criterio contenente degli spazi non significativi per renderlo più leggibile (si assuma che sia attiva l'opzione PCRE_EXTENDED) e lo si divida in tre parti per praticità di discussione: ( $ )? [^()]+ (?(1) $ )

La prima parte riconosce una parentesi aperta opzionale, e, se è presente, indica quello come primo segmento di stringa catturato. La seconda parte riconosce uno o più caratteri che non siano parentesi. Infine la terza parte è una sotto-regola condizionale che verifica se la prima parentesi è stata identifica o meno. Se accade, come nel caso in cui il testo inizi con una parentesi aperta, la condizione è TRUE, e quindi viene eseguito il ramo yes-pattern, richiedendo, conseguentemente, la parentesi chiusa. Diversamente, poiché non è specificato ramo no-pattern, non si esegue nessun altro riconoscimento. In altre parole questo criterio identifica un testo che possa essere racchiuso tra parentesi opzionali.

Se la condizione non è una sequenza di cifre, deve essere una asserzione. Questa può essere sia una asserzione che guarda avanti, sia una asserzione cha guarda indietro, sia positiva sia negativa. Si consideri il seguente criterio, ancora una volta contenente spazi non significativi, e con due alternative nella seconda linea:

       (?(?=[^a-z]*[a-z])
       \d{2}-[a-z]{3}-\d{2}  |  \d{2}-\d{2}-\d{2} )

La condizione è una asserzione che guarda avanti positiva, la quale identifica una sequenza opzionale di caratteri non alfabetici seguiti da una lettera. In altre parole, si testa la presenza di almeno una lettera nel testo. Se la lettera viene trovata si applica il primo criterio per il riconoscimento del testo, altrimenti viene applicato il secondo criterio. Questo criterio riconosce stringhe in due formati dd-aaa-dd oppure dd-dd-dd, dove aaa sono lettere e dd sono numeri.

Commenti

La sequenza (?# indica l'inizio di un commento che si conclude con la successiva parentesi chiusa. Parentesi annidate non sono permesse. I caratteri che fanno parte di un commento non giocano alcun ruolo nella fase di riconoscimento.

Se viene attivata l'opzione PCRE_EXTENDED, un carattere # privo della sequenza di escape (\) all'esterno di una classe di caratteri apre un commento che continua fino al carattere di "a capo".

Criteri ricorsivi

Si consideri il caso in cui si debba riconoscere una stringa tra parentesi, si supponga inoltre di dovere ammettere un numero arbitrario di parentesi annidate. Senza l'uso della ricorsione, il miglior metodo consiste nel preparare un criterio che identifichi un numero finito di parentesi annidate. Però, in questo modo non si gestisce un numero arbitrario si parentesi annidate. Nella versione 5.6 di Perl è stata introdotta, a livello sperimentale, la possibilità per i criteri di riconoscimento di essere ricorsivi. Allo scopo è stata definita la sequenza speciale (?R). Il criterio illustrato di seguito risolve il problema delle parentesi (si assume che l'opzione PCRE_EXTENDED sia attivata in modo da ignorare gli spazi): $ ( (?>[^()]+) | (?R) )* $

In principio si identifica la parentesi di apertura. Quindi si cerca un numero indefinito di stringhe che possano essere composte da caratteri che non siano parentesi, oppure che siano riconosciute ricorsivamente dal criterio (ad esempio una stringa correttamente tra parentesi). Infine si cerca la parentesi di chiusura.

In questo particolare esempio si hanno arbitrarie ripetizioni annidate, e quindi l'uso delle sotto-regole a riconoscimento singolo per il riconoscimento della stringa priva di parentesi è particolarmente utile se il criterio viene applicato ad un testo non riconoscibile. Ad esempio, applicando il criterio a (aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa() si ottiene un esito di mancato riconoscimento rapidamente. Se, al contrario, non si fosse usato il criterio a riconoscimento singolo, sarebbe occorso molto tempo per avere un esito dato che vi sono moltissimi modi in cui i caratteri di ripetizione + e * possono essere applicati al testo, richiedendo, pertanto, la verifica di tutte le combinazioni prima di fornire l'esito negativo.

Il valori restituiti da una sotto-regola di cattura sono quelli ottenuti dal livello di ricorsione più esterno. Se il criterio illustrato in precedenza venisse applicato al testo (ab(cd)ef) Il valore ottenuto sarebbe "ef", che rappresenta l'ultimo valore catturato al livello più alto. Se si aggiungono altre parentesi al criterio, ottenendo $ ( ( (?>[^()]+) | (?R) )* ) $ allora il testo ottenuto sarebbe "ab(cd)ef", cioè il valore delle parentesi di livello più alto. Se nel criterio vi sono più di 15 sotto-regole di cattura, PCRE ha necessità di ottenere maggiore memoria per archiviare le informazioni durante la ricorsione. Questa memoria è ottenuta utilizzando pcre_malloc, al termine verrà liberata con pcre_free. Se non può essere ottenuta ulteriore memoria, si ha il salvataggio delle informazioni dei primi 15 testi catturati, dato che non vi è modo di restituire un messaggio di memoria insufficiente dalla ricorsione.

Performances

Certi elementi utilizzati per i criteri di riconoscimento sono più efficienti di altri. E' più efficiente usare le classi di caratteri come [aeiou] piuttosto che un gruppo di alternative come (a|e|i|o|u). In generale la costruzione più semplice per ottenere un dato scopo è la più efficiente. Nel libro di Jeffrey Friedl sono illustrate varie tecniche sull'ottimizzazione delle espressioni regolari.

Quando un criterio comincia con .* ed è attiva l'opzione PCRE_DOTALL, il criterio è implicitamente ancorato da PCRE, dato che può rico- noscere solo l'inizio della stringa. Tuttavia, se non è attivo PCRE_DOTALL, PCRE non può fare questa ottimizzazione, perché il meta-carattere . non ri- conosce più il carattere di "a capo", e quindi se la stringa contiene dei caratteri di "a capo", il riconoscimento può par- tire dal carattere immediatamente successivo ad uno di questi e non dall'inizio. Ad esempio il criterio (.*) second può eseguire un riconoscimento nel testo "first\nand second" (dove \n indica il carattere "a capo") ottenendo "and" come prima stringa catturata. perché ciò accada è necessario che PCRE possa iniziare il riconoscimento dopo ogni "a capo".

Se si deve usare un simile criterio in stringhe che non conten- gono caratteri di "a capo", le performance migliori si possono ottenere abilitando PCRE_DOTALL, oppure iniziando il criterio con ^.* in modo da richiedere un ancoraggio esplicito. Così si risparmia a PCRE di scandirsi il testo alla ricerca di un "a capo" da cui ripartire per la ri- cerca.

Occorre prestare attenzione ai criteri che contengono ripeti- zioni indefinite annidate. Possono richiedere molto tempo se applicati a stringhe non riconoscibili. Si consideri il fram- mento (a+)*

Questo può riconoscere "aaaa" in 33 modi differenti, e questo numero può crescere molto rapidamente se la stringa da ricono- scere è più lunga. (Il carattere di ripetizione * può eseguire riconoscimenti per 0,1,2,3 o 4 ripetizioni, e per ciascuna di esse, tranne lo 0, il carattere di ripetizione + può esegui- re riconoscimenti per diversi numeri di volte). Quindi se la parte successiva del criterio è tale da non permettere il com- pletamento del riconoscimento, PCRE, per principio, ugualmente tenta tutte le possibili variazioni, richiedendo diverso tempo.

Una ottimizzazione riesce a catturare qualche caso semplice come in (a+)*b dove si indica che seguirà un carattere alfanumerico. PCRE, prima di imbarcarsi nella procedura standard di riconoscimen- to, verifica se nel testo vi è la lettera "b", e se non c'è restituisce immediatamente un esito negativo. Tuttavia se non viene indicata una lettera seguente questa ottimizzazione non può essere utilizzata. Se ne può notare la differenza analiz- zando il comportamento del criterio (a+)*\d rispetto al precedente. Il primo, utilizzato con una stringa composta da "a", fallisce immediatamente, l'ultimo richiede un tempo apprezzabile, soprattutto se applicato a stringhe con più di 20 caratteri.

preg_grep

(PHP 4, PHP 5)

preg_grep -- Restituisce una matrice degli elementi riconosciuti tramite le espressioni regolari

Descrizione

array preg_grep ( string espressione_regolare, array testo [, int flags] )

La funzione preg_grep() restituisce una matrice composta dagli elementi dell'array testo che soddisfano i criteri impostati nel parametro espressione_regolare.

Il parametro flags può assumere i seguenti valori:

PREG_GREP_INVERT: Con questo valore, la funzione preg_grep()gli elementi della matrice di input che non soddisfano la data espressione_regolare. Questo valore è disponibile a partire da PHP 4.2.0.

A partire dalla versione 4.0.4 di PHP, la matrice risultante dalla funzione preg_grep(), viene indicizzata utilizzando le chiavi dalla matrice di input. Se non si desidera un comportamento simile, applicare la funzione array_values() alla matrice ottenuta da questa funzione per ricalcolare gli indici.

Esempio 1. Esempio di preg_grep()
<?php // esempio di restituzione di tutti gli elementi della matrice // contenenti numeri in virgola mobile $fl_array = preg_grep("/^(\d+)?\.\d+$/", $array); ?>

preg_match_all

(PHP 3 >= 3.0.9, PHP 4, PHP 5)

preg_match_all -- Esegue un riconoscimento globale con le espressioni regolari

Descrizione

int preg_match_all ( string espressione_regolare, string testo, array &TestiRiconosciuti [, int flags [, int offset]] )

La funzione ricerca tutte le espressioni regolari passate nel parametro espressione_regolare all'interno della stringa testo. I testi riconosciuti sono posti all'interno della matrice TestiRiconosciuti, nell'ordine specificato da flags.

Dopo avere riconosciuto il primo segmento di testo, le ricerche seguenti saranno effettuate a partire dall'ultima ricerca specificata.

Il parametro flags può essere la combinazione dei seguenti flag (da notare che non ha senso utilizzare PREG_PATTERN_ORDER in unione a PREG_SET_ORDER):

PREG_PATTERN_ORDER

I testi riconosciuti saranno organizzati in modo tale da avere in $TestiRiconosciuti[0] la matrice di tutti i testi riconosciuti, in $TestiRiconosciuti[1] la matrice di tutti i testi che soddisfino il primo criterio di riconoscimento posto tra parentesi tonde, in $TestiRiconosciuti[2] si avranno i testi che soddisfino il secondo criterio e cosi via.

<?php
preg_match_all("|<[^>]+>(.*)</[^>]+>|U",
    "<b>example: </b><div align=left>this is a test</div>", 
    $out, PREG_PATTERN_ORDER);
echo $out[0][0].", ".$out[0][1]."\n";
echo $out[1][0].", ".$out[1][1]."\n";
?>

Questo esempio produrrà:

<b>example: </b>, <div align=left>this is a test</div>
example: , this is a test

Nell'esempio, $out[0] contiene la matrice di tutte le stringhe che soddisfano i criteri impostati, $out[1] contiene la matrice dei testi delimitati dai tag.

PREG_SET_ORDER

Usando questo parametro come ordine dei riconoscimenti, si avrà in $TestiRiconosciuti[0] una matrice con il primo set di testi riconosciuti, in $TestiRiconosciuti[1], la matrice con il secondo set di testi riconosciuti e così via.

<?php
preg_match_all("|<[^>]+>(.*)</[^>]+>|U",
    "<b>example: </b><div align=\"left\">this is a test</div>",
    $out, PREG_SET_ORDER);
echo $out[0][0].", ".$out[0][1]."\n";
echo $out[1][0].", ".$out[1][1]."\n";
?>

Questo esempio visualizzerà:

<b>example: </b>, example: 
<div align="left">this is a test</div>, this is a test

In questo esempio $out[0] è la matrice del primo set di testi riconosciuti. Nel dettaglio $out[0][0] conterrà il testo che incrocia l'intero criterio impostato, $out[0][1] conterrà il testo riconosciuto tramite il prima regola di riconoscimento presente nel criterio globale. Analogo discorso si può fare per $out[1]. In questo caso il ragionamento verrà svolto su un secondo segmento della stringa che soddisfi le condizioni poste dal criterio di riconoscimento.

PREG_OFFSET_CAPTURE

Se viene impostato questo flag, per ogni testo riconosciuto viene restituito l'offset della stringa. Occorre notare che questo cambia il tipo di valore restituito nell'array, infatti ogni elemento è, a sua volta, un'array composto dalla stringa riconosciuta, all'indice 0, e dall'offset della stringa nell'indice 1. Questa costante è disponibile a partire dalla versione 4.3.0 di PHP.

Qualora non si specifichi il parametro flags, si assume per default il valore PREG_PATTERN_ORDER.

Normalemente la ricerca parte dall'inizio della stringa oggetto di ricerca. Con il parametro opzionale offset si può specificare da dove cominciare la ricerca. Equivale a passare substr()($testo, $offset) alla funzione preg_match() al posto del parametro testo. Il parametro offset è disponibile a partire dalla versione 4.3.3 di PHP.

La funzione restituisce il numero dei riconoscimenti completi svolti (che possono essere zero), oppure FALSE se si verificano degli errori.

Esempio 1. Esempio di come ottenere tutti i numeri di telefono da un testo.
<?php preg_match_all("/$? (\d{3})? $? (?(1) [\-\s] ) \d{3}-\d{4}/x", "Call 555-1212 or 1-800-555-1212", $numeri); ?>

Esempio 2. Ricerca di tag HTML
<?php // Il parametro \\2 è un esempio di riferimento all'indietro. Questo dato informa la // libreria pcre che deve considerare il secondo set di parentesi tonde (in questo // caso il testo "([\w]+)"). Il backslash (\) aggiuntivo è reso obbligatorio dall'uso // dei doppi apici. $html = "<b>bold text</b><a href=howdy.html>click me</a>"; preg_match_all("/(<([\w]+)[^>]*>)(.*)(<\/\\2>)/", $html, $matches); for ($i=0; $i< count($matches[0]); $i++) { echo "intero criterio: ".$matches[0][$i]."\n"; echo "parte 1: " . $matches[1][$i] . "\n"; echo "parte 2: " . $matches[3][$i] . "\n"; echo "parte 3: " . $matches[4][$i] . "\n\n"; } ?>
Questo esempio visualizzerà:
intero criterio: <b>bold text</b> parte 1: <b> parte 2: bold text parte 3: </b> intero criterio: <a href=howdy.html>click me</a> parte 1: <a href=howdy.html> parte 2: click me parte 3: </a>

Vedere anche preg_match(), preg_replace() e preg_split().

preg_match

(PHP 3 >= 3.0.9, PHP 4, PHP 5)

preg_match -- Riconoscimento con espressioni regolari

Descrizione

mixed preg_match ( string criterio, string testo [, array &testi_riconosciuti [, int flags [, int offset]]] )

Esegue un riconoscimento nel parametro testo utilizzando l'espressione regolare indicata in criterio.

Se viene fornito il terzo parametro, testi_riconosciuti, questo verrà valorizzato con i risultati della ricerca. In dettaglio $testi_riconosciuti[0] conterrà il testo che si incrocia con l'intero criterio di ricerca, $testi_riconosciuti[1] conterrà il testo che soddisfa il primo criterio posto tra parentesi, $testi_riconosciuti[2] il secondo e così via.

Il parametro flags può assumere i seguenti valori:

PREG_OFFSET_CAPTURE: Se viene impostato questo flag, per ogni testo riconosciuto viene restituito l'offset della stringa. Occorre notare che questo cambia il tipo di valore restituito nell'array, infatti ogni elemento è, a sua volta, un'array composto dalla stringa riconosciuta, all'indice 0, e dall'offset della stringa nell'indice 1. Questa costante è disponibile a partire dalla versione 4.3.0 di PHP.

Il parametro flags è disponibile a partire dalla versione 4.3.0 di PHP.

La funzione preg_match() restituisce il numero di volte in cui è avvenuto il riconoscimento del criterio. Questo può essere 0 (nessun riconoscimento) oppure 1 se preg_match() si ferma dopo il primo riconoscimento. In condizioni normali, preg_match_all() continua il riconoscimento fino alla fine del parametro testo. preg_match() restituirà FALSE se si verifica un errore.

Suggerimento: Non utilizzare la funzione preg_match() se si desidera controllare se una stringa è contenuta in un'altra. Piuttosto utilizzare strpos() oppure strstr() che sono più veloci.

Esempio 1. Ricerca del testo "php"
<?php // La lettera "i" dopo i delimitatori indica una ricerca case-insensitive if (preg_match("/php/i", "PHP è il linguaggio scelto.")) { echo "Il riconoscimento è avvenuto."; } else { echo "Testo non riconosciuto."; } ?>

Esempio 2. Cerca la parola "web"
<?php // La lettera \b nel criterio indica i limiti della parola. Così verrà riconosciuta solo // la parola "web" e non parte di una parola più lunga come "webbing" oppure "cobweb" if (preg_match("/\bweb\b/i", "PHP è un linguaggio di programmazione per il web scelto da molti.")) { echo "Il riconoscimento è avvenuto."; } else { echo "Testo non riconosciuto."; } if (preg_match("/\bweb\b/i", "PHP è un linguaggio di programmazione installato su molti website")) { echo "Il riconoscimento è avvenuto."; } else { echo "Testo non riconosciuto."; } ?>

Esempio 3. Estrapolazione del dominio da un URL
<?php // come ottenere il nome dell'host da un URL preg_match("/^(http:\/\/)?([^\/]+)/i", "http://www.php.net/index.html", $matches); $NomeHost = $matches[2]; // come ottenere gli ultimi due segmenti del nome dell'host preg_match("/[^\.\/]+\.[^\.\/]+$/",$NomeHost,$matches); echo "Nome del dominio: {$matches[0]}\n"; ?>
L'esempio visualizzerà:
Nome del dominio: php.net

Vedere anche preg_match_all(), preg_replace() e preg_split().

preg_quote

(PHP 3 >= 3.0.9, PHP 4, PHP 5)

preg_quote -- Inserisce il carattere di escape nei caratteri delle espressioni regolari

Descrizione

string preg_quote ( string stringa [, string delimitatori] )

La funzione preg_quote() inserisce il carattere di escape (\) davanti ad ogni carattere presente in stringa che sia parte della sintassi di una espressione regolare. Questa funzione è utile nei casi in cui si generino, durante l'esecuzione, delle stringhe da usare come criteri di riconoscimento, e queste possano contenere dei caratteri speciali per le espressioni regolari.

Se viene specificato un carattere come parametro delimitatore, anche a questo sarà anteposto il carattere di escape (\). Ciò è particolarmente utile per porre il carattere di escape nei delimitatori richiesti dalle funzioni PCRE. Il carattere di delimitazione più comunemente utilizzato è /.

I caratteri speciali per le espressioni regolari sono: . \\ + * ? [ ^ ] $ ( ) { } = ! < > | :

Esempio 1. Esempio di preg_quote()
<?php $keywords = "$40 for a g3/400"; $keywords = preg_quote($keywords, "/"); echo $keywords; // returns \$40 for a g3\/400 ?>

Esempio 2. Esempio di come rendere in corsivo una qualsiasi parola di un testo
<?php // In questo esempio, la funzione preg_quote($word) viene usata // per impedire agli asterischi di avere il loro significato // speciale per le espressioni regolari. $testo = "Questo libro è *molto* difficile da trovare."; $parola = "*molto*"; $testo = preg_replace("/". preg_quote($parola) . "/", "<i>" . $parola . "</i>", $testo); ?>

Nota: Questa funzione è binary-safe (gestisce correttamente i file binari)

preg_replace_callback

(PHP 4 >= 4.0.5, PHP 5)

preg_replace_callback -- Esegue ricerche e sostituzioni con espressioni regolari usando il callback

Descrizione

mixed preg_replace_callback ( mixed espressione_regolare, callback callback, mixed testo [, int limite] )

Fondamentalmente questa funzione si comporta come preg_replace(), eccetto che per la presenza del callback. Con quest'ultimo parametro si indica una funzione da richiamare a cui verrà passata una matrice con i testi riconosciuti in testo. La funzione di callback dovrebbe restituire la stringa da sostituire.

Esempio 1. Esempio dell'uso di preg_replace_callback()

<?php 
// questo test è stato usato nel 2002
// lo si vuole avere aggiornato per il 2003
$text = "April fools day is 04/01/2002\n"; 
$text.= "Last christmas was 12/24/2001\n"; 
// la funzione di callback
function next_year($matches) 
{ 
// come solito: $matches[0] è il testo riconosciuto completo
// $matches[1] la parte riconosciuta per il primo criterio
// racchiuso in '(...)' e così via
return $matches[1].($matches[2]+1); 
}
echo preg_replace_callback(
     "|(\d{2}/\d{2}/)(\d{4})|",
     "next_year",
     $text);
// il risultato sarà:
// April fools day is 04/01/2003
// Last christmas was 12/24/2002
?>

Spesso si ha la necessità di richiamare la funzione callback soltanto in un unico posto. In questo caso si può utilizzare create_function() per dichiarare una funzione anonima come callback per preg_replace_callback().In questo modo si hanno tutte le informazioni per la chiamata in un unico posto e non si disperde con funzioni di callback non utilizzate altrove.

Esempio 2. preg_replace_callback() e create_function()

<?php
/* Un filtro da linea di comando stile Unix che converte
 * la maiuscole poste all'inizio delle parole in minuscolo */
$fp = fopen("php://stdin", "r") or die("can't read stdin");
while (!feof($fp)) {
      $line = fgets($fp);
      $line = preg_replace_callback(
             '|<p>\s*\w|',
             create_function(
                  // l'apice singolo è essenziale qui, 
                  // o in alternativa occorre usare la sequenza di escape \$ 
                  // per tutte le occorrenze di $ 
                 '$matches',
                 'return strtolower($matches[0]);' 
                 ), 
               $line 
      );
      echo $line; 
}
fclose($fp);
?>

Vedere anche preg_replace() create_function(), e information about the callback type.

preg_replace

(PHP 3 >= 3.0.9, PHP 4, PHP 5)

preg_replace -- Esegue una ricerca ed una sostituzione con le espressioni regolari

Descrizione

mixed preg_replace ( mixed espressione_regolare, mixed sostituto, mixed testo [, int limite] )

La funzione ricerca in testo i criteri impostati in espressione_regolare. Se riconosce dei testi, li sostituisce con sostituto. Se si specifica limite, verranno sostituiti solamente limite testi riconosciuti; se viene omesso, oppure impostato a -1, verranno sostituiti tutti i testi riconosciuti.

Il parametro sostituto può contenere riferimenti nella forma di \\n, oppure, a partire dalla versione 4.0.4 di PHP, $n, con la preferenza per la seconda sintassi. Questo tipo di riferimento verrà sostituito dal testo che soddisfa l'n-esimo criterio presente in espressione_regolare. Sono ammessi numeri compresi tra 0 e 99 inclusi. Il valore 0 (\\0 oppure $0) si riferisce al testo riconosciuto tramite tutta l'espressione regolare passata. Nel conteggio dei criteri di riconoscimento presenti, sono contate le parentesi aperte da sinistra verso destra partendo da 1.

Quando si lavora con un criterio di sostituzione in cui un riferimento all'indietro è immediatamente seguito da un'altro numero (ad esempio un numero che segue immediatamente il criterio riconosciuto), non si possono utilizzare le solite notazioni, \\1, per i riferimenti all'indietro. Ad esempio, il testo \\11 confonderebbe preg_replace() poichè non saprebbe se si desidera il riferimento all'indietro \\1 seguito dal numero 1, oppure se è desiderato il riferimento \\11 seguito da niente. In questi casi la soluzione consiste nell'uso di \${1}1. In questo modo si crea un riferimento all'indietro $1 isolato dal numero 1.

Esempio 1. Uso dei riferimenti all'indietro seguiti da numeri
<?php $string = "April 15, 2003"; $pattern = "/(\w+) (\d+), (\d+)/i"; $replacement = "\${1}1,\$3"; echo preg_replace($pattern, $replacement, $string); ?>
This example will output :
April1,2003

Se verranno riconosciuti dei testi, la funzione restituisce la nuova versione di testo, altrimenti il parametro sarà restituito inalterato.

Ogni parametro passato alla funzione preg_replace(), (eccetto limite) può essere una matrice ad una dimensione. Quando si utilizzano matrici con espressione_regolare e sostituto, le chiavi sono processate nell'ordine con cui appaiono nella matrice. Questo non è necessariamente l'ordine numerico dell'indice. Se si utilizzano degli indici per identificare quale espressione_regolare debba essere sostituita da sostituto, occorre eseguire la funzione ksort() su ciascuna matrice prima di eseguire preg_replace().

Esempio 2. Uso di matrici indicizzate con preg_replace()
<?php $string = "The quick brown fox jumped over the lazy dog."; $patterns[0] = "/quick/"; $patterns[1] = "/brown/"; $patterns[2] = "/fox/"; $replacements[2] = "bear"; $replacements[1] = "black"; $replacements[0] = "slow"; echo preg_replace($patterns, $replacements, $string); ?>
Output:
The bear black slow jumped over the lazy dog.
Utilizzando ksort su entrambe le matrici otteniamo cio che vogliamo.
<?php ksort($patterns); ksort($replacements); echo preg_replace($patterns, $replacements, $string); ?>
Output :
The slow black bear jumped over the lazy dog.

Se il campo testo è una matrice, la ricerca e la sostituzione sarà eseguita su ogni elemento della matrice, e conseguentemente la funzione restituirà una matrice.

Se espressione_regolare ed sostituto sono entrambi delle matrici, la funzione preg_replace() utilizza gli elementi di ciascuna matrice per la ricerca e la sostituzione delle stringhe in testo. Nel caso in cui la matrice passata in sostituto abbia meno elementi che espressione_regolare, la funzione utilizzerà una stringa vuota per compensare gli elementi mancanti nella fase di sostituzione. Se, invece, espressione_regolare è una matrice, mentre il campo sostituto è una stringa, quest'ultima sarà usata come valore da sostituire ad ogni testo riconosciuto. Un discorso contrario non ha senso.

Il modificatore /e, permette alla funzione di considerare il testo posto in sostituto come codice PHP dopo aver valorizzato gli opportuni riferimenti. Suggerimento: accertarsi che sostituto sia del codice PHP valido, altrimenti si ottiene un errore di parsing alla linea della funzione preg_replace().

Esempio 3. Esempi di sostituzione di valori
<?php $patterns = array ("/(19|20)(\d{2})-(\d{1,2})-(\d{1,2})/", "/^\s*{(\w+)}\s*=/"); $replace = array ("\\3/\\4/\\1\\2", "$\\1 ="); echo preg_replace($patterns, $replace, "{startDate} = 1999-5-27"); ?>
Questo esempio visualizzerà:
$startDate = 5/27/1999

Esempio 4. Utilizzo del modificatore /e
<?php preg_replace("/(<\/?)(\w+)([^>]*>)/e", "'\\1'.strtoupper('\\2').'\\3'", $html_body); ?>
Nell'esempio precedente tutti i tag HTML presenti nel testo di input saranno convertiti in maiuscolo.

Esempio 5. Esempio di conversione di codice HTML in testo
<?php // $document contiene un documento HTML. // In questo esempio la funzione rimuove i tag HTML, // le sezioni javascript e gli spazi bianchi. // Inoltre si convertirà le entità HTML nella loro // rappresentazione testuale. $search = array ("'<script[^>]*?>.*?</script>'si", // Rimozione del javascript "'<[\/\!]*?[^<>]*?>'si", // Rimozione dei tag HTML "'([\r\n])[\s]+'", // Rimozione degli spazi bianchi "'&(quot|#34);'i", // Sostituzione delle entità HTML "'&(amp|#38);'i", "'&(lt|#60);'i", "'&(gt|#62);'i", "'&(nbsp|#160);'i", "'&(iexcl|#161);'i", "'&(cent|#162);'i", "'&(pound|#163);'i", "'&(copy|#169);'i", "'&#(\d+);'e"); // Valuta come codice PHP $replace = array ("", "", "\\1", "\"", "&", "<", ">", " ", chr(161), chr(162), chr(163), chr(169), "chr(\\1)"); $text = preg_replace($search, $replace, $document); ?>

Nota: Il parametro limite è stato aggiunto successivamente alla versione 4.0.1pl2 di PHP.

Vedere anche preg_match(), preg_match_all() e preg_split().

preg_split

(PHP 3 >= 3.0.9, PHP 4, PHP 5)

preg_split -- Suddivisione di una stringa tramite le espressioni regolari

Descrizione

array preg_split ( string espressione_regolare, string testo [, int limite [, int flags]] )

La funzione restituisce una matrice di parti di testo suddivisi tramite i criteri indicati da espressione_regolare.

Se viene specificato il parametro limite, la funzione restituisce tante parti del testo iniziale quante sono indicate da limite. Può essere usato il valore -1 per indicare "nessun limite". Ciò torna utile in abbinamento all'uso del parametro flags.

Il parametro flags può essere la combinazione dei seguenti flag (la combinazione di più flag avviene con l'operatore |):

PREG_SPLIT_NO_EMPTY: Specificando questo flag, la funzione preg_split() restituisce spezzoni di testo non vuoti.
PREG_SPLIT_DELIM_CAPTURE: Con l'uso di questo flag, la funzione cattura e restituisce eventuali espressioni poste tra parentesi nel parametro espressione_regolare. Questo flag è stato aggiunto nella versione 4.0.5.
PREG_SPLIT_OFFSET_CAPTURE: Se viene impostato questo flag, per ogni testo riconosciuto viene restituito l'offset della stringa. Occorre notare che questo cambia il tipo di valore restituito nell'array; infatti ogni elemento è, a sua volta, un'array composto dalla stringa riconosciuta, all'indice 0, e dall'offset della stringa nell'indice 1. Questa costante è disponibile a partire dalla versione 4.3.0 di PHP.

Esempio 1. Esempio di preg_split(): Come ottenere le parti di un testo.
<?php // Suddivide la seguente frase in base alla presenza di virgole, spazi bianchi, // e altri caratteri speciali quali \r, \t, \n ed \f $keywords = preg_split("/[\s,]+/", "hypertext language, programming"); ?>

Esempio 2. Esempio di suddivisione di un testo in caratteri.
<?php $str = 'string'; $chars = preg_split('//', $str, -1, PREG_SPLIT_NO_EMPTY); print_r($chars); ?>

Esempio 3. Suddivisione di una stringa in testi riconosciuti con i relativi offset.
<?php $str = 'hypertext language programming'; $chars = preg_split('/ /', $str, -1, PREG_SPLIT_OFFSET_CAPTURE); print_r($chars); ?>
visualizzerà
Array ( [0] => Array ( [0] => hypertext [1] => 0 ) [1] => Array ( [0] => language [1] => 10 ) [2] => Array ( [0] => programming [1] => 19 ) )

Nota: Il parametro flags è stato aggiunto nella versione 4 Beta 3 di PHP.

Vedere anche spliti(), split(), implode(), preg_match(), preg_match_all() e preg_replace().

CIX. PDF functions

Introduzione

The PDF functions in PHP can create PDF files using the PDFlib library created by Thomas Merz.

The documentation in this section is only meant to be an overview of the available functions in the PDFlib library and should not be considered an exhaustive reference. Please consult the documentation included in the source distribution of PDFlib for the full and detailed explanation of each function here. It provides a very good overview of what PDFlib is capable of doing and contains the most up-to-date documentation of all functions.

All of the functions in PDFlib and the PHP module have identical function names and parameters. You will need to understand some of the basic concepts of PDF and PostScript to efficiently use this extension. All lengths and coordinates are measured in PostScript points. There are generally 72 PostScript points to an inch, but this depends on the output resolution. Please see the PDFlib documentation included with the source distribution of PDFlib for a more thorough explanation of the coordinate system used.

Please note that most of the PDF functions require a pdfdoc as its first parameter. Please see the examples below for more information.

Nota: If you're interested in alternative free PDF generators that do not utilize external PDF libraries, see this related FAQ.

Nota: This extension has been moved to PECL as of PHP 4.3.9.

Requisiti

PDFlib is available for download at http://www.pdflib.com/products/pdflib/index.html, but requires that you purchase a license for commercial use. The JPEG and TIFF libraries are required to compile this extension.

Issues with older versions of PDFlib

Any version of PHP 4 after March 9, 2000 does not support versions of PDFlib older than 3.0.

PDFlib 3.0 or greater is supported by PHP 3.0.19 and later.

Installazione

To get these functions to work in PHP < 4.3.9, you have to compile PHP with --with-pdflib[=DIR]. DIR is the PDFlib base install directory, defaults to /usr/local. In addition you can specify the jpeg, tiff, and pnglibrary for PDFlib to use, which is optional for PDFlib 4.x. To do so add to your configure line the options --with-jpeg-dir[=DIR] --with-png-dir[=DIR] --with-tiff-dir[=DIR].

When using version 3.x of PDFlib, you should configure PDFlib with the option --enable-shared-pdflib.

As of PHP 4.3.9, you must install this extension through PEAR, using the following command: pear install pdflib.

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Confusion with old PDFlib versions

Starting with PHP 4.0.5, the PHP extension for PDFlib is officially supported by PDFlib GmbH. This means that all the functions described in the PDFlib manual (V3.00 or greater) are supported by PHP 4 with exactly the same meaning and the same parameters. Only the return values may differ from the PDFlib manual, because the PHP convention of returning FALSE was adopted. For compatibility reasons, this binding for PDFlib still supports the old functions, but they should be replaced by their new versions. PDFlib GmbH will not support any problems arising from the use of these deprecated functions.

Tabella 1. Deprecated functions and their replacements

Old function	Replacement
pdf_put_image()	Not needed anymore.
pdf_execute_image()	Not needed anymore.
pdf_get_annotation()	pdf_get_bookmark() using the same parameters.
pdf_get_font()	pdf_get_value() passing `"font"` as the second parameter.
pdf_get_fontsize()	pdf_get_value() passing `"fontsize"` as the second parameter.
pdf_get_fontname()	pdf_get_parameter() passing `"fontname"` as the second parameter.
pdf_set_info_creator()	pdf_set_info() passing `"Creator"` as the second parameter.
pdf_set_info_title()	pdf_set_info() passing `"Title"` as the second parameter.
pdf_set_info_subject()	pdf_set_info() passing `"Subject"` as the second parameter.
pdf_set_info_author()	pdf_set_info() passing `"Author"` as the second parameter.
pdf_set_info_keywords()	pdf_set_info() passing `"Keywords"` as the second parameter.
pdf_set_leading()	pdf_set_value() passing `"leading"` as the second parameter.
pdf_set_text_rendering()	pdf_set_value() passing `"textrendering"` as the second parameter.
pdf_set_text_rise()	pdf_set_value() passing `"textrise"` as the second parameter.
pdf_set_horiz_scaling()	pdf_set_value() passing `"horizscaling"` as the second parameter.
pdf_set_text_matrix()	Not available anymore
pdf_set_char_spacing()	pdf_set_value() passing `"charspacing"` as the second parameter.
pdf_set_word_spacing()	pdf_set_value() passing `"wordspacing"` as the second parameter.
pdf_set_transition()	pdf_set_parameter() passing `"transition"` as the second parameter.
pdf_open()	pdf_new() plus an subsequent call of pdf_open_file()
pdf_set_font()	pdf_findfont() plus an subsequent call of pdf_setfont()
pdf_set_duration()	pdf_set_value() passing `"duration"` as the second parameter.
pdf_open_gif()	pdf_open_image_file() passing `"gif"` as the second parameter.
pdf_open_jpeg()	pdf_open_image_file() passing `"jpeg"` as the second parameter.
pdf_open_tiff()	pdf_open_image_file() passing `"tiff"` as the second parameter.
pdf_open_png()	pdf_open_image_file() passing `"png"` as the second parameter.
pdf_get_image_width()	pdf_get_value() passing `"imagewidth"` as the second parameter and the image as the third parameter.
pdf_get_image_height()	pdf_get_value() passing `"imageheight"` as the second parameter and the image as the third parameter.

Esempi

Most of the functions are fairly easy to use. The most difficult part is probably creating your first PDF document. The following example should help to get you started. It creates test.pdf with one page. The page contains the text "Times Roman outlined" in an outlined, 30pt font. The text is also underlined.

Esempio 1. Creating a PDF document with PDFlib
<?php $pdf = pdf_new(); pdf_open_file($pdf, "test.pdf"); pdf_set_info($pdf, "Author", "Uwe Steinmann"); pdf_set_info($pdf, "Title", "Test for PHP wrapper of PDFlib 2.0"); pdf_set_info($pdf, "Creator", "See Author"); pdf_set_info($pdf, "Subject", "Testing"); pdf_begin_page($pdf, 595, 842); pdf_add_outline($pdf, "Page 1"); $font = pdf_findfont($pdf, "Times New Roman", "winansi", 1); pdf_setfont($pdf, $font, 10); pdf_set_value($pdf, "textrendering", 1); pdf_show_xy($pdf, "Times Roman outlined", 50, 750); pdf_moveto($pdf, 50, 740); pdf_lineto($pdf, 330, 740); pdf_stroke($pdf); pdf_end_page($pdf); pdf_close($pdf); pdf_delete($pdf); echo "<A HREF=getpdf.php>finished</A>"; ?>
The script getpdf.php just returns the pdf document.
Esempio 2. Outputting a precalculated PDF
<?php $len = filesize($filename); header("Content-type: application/pdf"); header("Content-Length: $len"); header("Content-Disposition: inline; filename=foo.pdf"); readfile($filename); ?>

The PDFlib distribution contains a more complex example which creates a page with an analog clock. Here we use the in-memory creation feature of PDFlib to alleviate the need to use temporary files. The example was converted to PHP from the PDFlib example. (The same example is available in the CLibPDF documentation.)

Esempio 3. pdfclock example from PDFlib distribution
<?php $radius = 200; $margin = 20; $pagecount = 10; $pdf = pdf_new(); if (!pdf_open_file($pdf, "")) { echo error; exit; }; pdf_set_parameter($pdf, "warning", "true"); pdf_set_info($pdf, "Creator", "pdf_clock.php"); pdf_set_info($pdf, "Author", "Uwe Steinmann"); pdf_set_info($pdf, "Title", "Analog Clock"); while ($pagecount-- > 0) { pdf_begin_page($pdf, 2 * ($radius + $margin), 2 * ($radius + $margin)); pdf_set_parameter($pdf, "transition", "wipe"); pdf_set_value($pdf, "duration", 0.5); pdf_translate($pdf, $radius + $margin, $radius + $margin); pdf_save($pdf); pdf_setrgbcolor($pdf, 0.0, 0.0, 1.0); /* minute strokes */ pdf_setlinewidth($pdf, 2.0); for ($alpha = 0; $alpha < 360; $alpha += 6) { pdf_rotate($pdf, 6.0); pdf_moveto($pdf, $radius, 0.0); pdf_lineto($pdf, $radius-$margin/3, 0.0); pdf_stroke($pdf); } pdf_restore($pdf); pdf_save($pdf); /* 5 minute strokes */ pdf_setlinewidth($pdf, 3.0); for ($alpha = 0; $alpha < 360; $alpha += 30) { pdf_rotate($pdf, 30.0); pdf_moveto($pdf, $radius, 0.0); pdf_lineto($pdf, $radius-$margin, 0.0); pdf_stroke($pdf); } $ltime = getdate(); /* draw hour hand */ pdf_save($pdf); pdf_rotate($pdf,-(($ltime['minutes']/60.0)+$ltime['hours']-3.0)*30.0); pdf_moveto($pdf, -$radius/10, -$radius/20); pdf_lineto($pdf, $radius/2, 0.0); pdf_lineto($pdf, -$radius/10, $radius/20); pdf_closepath($pdf); pdf_fill($pdf); pdf_restore($pdf); /* draw minute hand */ pdf_save($pdf); pdf_rotate($pdf,-(($ltime['seconds']/60.0)+$ltime['minutes']-15.0)*6.0); pdf_moveto($pdf, -$radius/10, -$radius/20); pdf_lineto($pdf, $radius * 0.8, 0.0); pdf_lineto($pdf, -$radius/10, $radius/20); pdf_closepath($pdf); pdf_fill($pdf); pdf_restore($pdf); /* draw second hand */ pdf_setrgbcolor($pdf, 1.0, 0.0, 0.0); pdf_setlinewidth($pdf, 2); pdf_save($pdf); pdf_rotate($pdf, -(($ltime['seconds'] - 15.0) * 6.0)); pdf_moveto($pdf, -$radius/5, 0.0); pdf_lineto($pdf, $radius, 0.0); pdf_stroke($pdf); pdf_restore($pdf); /* draw little circle at center */ pdf_circle($pdf, 0, 0, $radius/30); pdf_fill($pdf); pdf_restore($pdf); pdf_end_page($pdf); # to see some difference sleep(1); } pdf_close($pdf); $buf = pdf_get_buffer($pdf); $len = strlen($buf); header("Content-type: application/pdf"); header("Content-Length: $len"); header("Content-Disposition: inline; filename=foo.pdf"); echo $buf; pdf_delete($pdf); ?>

Vedere anche:

Nota: An alternative PHP module for PDF document creation based on FastIO's ClibPDF is available. Please see the ClibPDF section for details. Note that ClibPDF has a slightly different API than PDFlib.

Sommario
pdf_add_annotation -- Deprecated: Adds annotation
pdf_add_bookmark -- Adds bookmark for current page
pdf_add_launchlink -- Add a launch annotation for current page
pdf_add_locallink -- Add a link annotation for current page
pdf_add_note -- Sets annotation for current page
pdf_add_outline -- Deprecated: Adds bookmark for current page
pdf_add_pdflink -- Adds file link annotation for current page
pdf_add_thumbnail -- Adds thumbnail for current page
pdf_add_weblink -- Adds weblink for current page
pdf_arc -- Draws an arc (counterclockwise)
pdf_arcn -- Draws an arc (clockwise)
pdf_attach_file -- Adds a file attachment for current page
pdf_begin_page -- Starts new page
pdf_begin_pattern -- Starts new pattern
pdf_begin_template -- Starts new template
pdf_circle -- Draws a circle
pdf_clip -- Clips to current path
pdf_close_image -- Closes an image
pdf_close_pdi_page -- Close the page handle
pdf_close_pdi -- Close the input PDF document
pdf_close -- Closes a pdf resource
pdf_closepath_fill_stroke -- Closes, fills and strokes current path
pdf_closepath_stroke -- Closes path and draws line along path
pdf_closepath -- Closes path
pdf_concat -- Concatenate a matrix to the CTM
pdf_continue_text -- Outputs text in next line
pdf_curveto -- Draws a curve
pdf_delete -- Deletes a PDF object
pdf_end_page -- Ends a page
pdf_end_pattern -- Finish pattern
pdf_end_template -- Finish template
pdf_endpath -- Deprecated: Ends current path
pdf_fill_stroke -- Fills and strokes current path
pdf_fill -- Fills current path
pdf_findfont -- Prepare font for later use with pdf_setfont()
pdf_get_buffer -- Fetch the buffer containing the generated PDF data
pdf_get_font -- Deprecated: font handling
pdf_get_fontname -- Deprecated: font handling
pdf_get_fontsize -- Deprecated: font handling
pdf_get_image_height -- Deprecated: returns height of an image
pdf_get_image_width -- Deprecated: Returns width of an image
pdf_get_majorversion -- Returns the major version number of the PDFlib
pdf_get_minorversion -- Returns the minor version number of the PDFlib
pdf_get_parameter -- Gets certain parameters
pdf_get_pdi_parameter -- Get some PDI string parameters
pdf_get_pdi_value -- Gets some PDI numerical parameters
pdf_get_value -- Gets certain numerical value
pdf_initgraphics -- Resets graphic state
pdf_lineto -- Draws a line
pdf_makespotcolor -- Makes a spotcolor
pdf_moveto -- Sets current point
pdf_new -- Creates a new pdf resource
pdf_open_ccitt -- Opens a new image file with raw CCITT data
pdf_open_file -- Opens a new pdf object
pdf_open_gif -- Deprecated: Opens a GIF image
pdf_open_image_file -- Reads an image from a file
pdf_open_image -- Versatile function for images
pdf_open_jpeg -- Deprecated: Opens a JPEG image
pdf_open_memory_image -- Opens an image created with PHP's image functions
pdf_open_pdi_page -- Prepare a page
pdf_open_pdi -- Opens a PDF file
pdf_open_png -- Deprecated: Opens a PNG image
pdf_open_tiff -- Deprecated: Opens a TIFF image
pdf_open -- Deprecated: Open a new pdf object
pdf_place_image -- Places an image on the page
pdf_place_pdi_page -- Places an image on the page
pdf_rect -- Draws a rectangle
pdf_restore -- Restores formerly saved environment
pdf_rotate -- Sets rotation
pdf_save -- Saves the current environment
pdf_scale -- Sets scaling
pdf_set_border_color -- Sets color of border around links and annotations
pdf_set_border_dash -- Sets dash style of border around links and annotations
pdf_set_border_style -- Sets style of border around links and annotations
pdf_set_char_spacing -- Deprecated: Sets character spacing
pdf_set_duration -- Deprecated: Sets duration between pages
pdf_set_font -- Deprecated: Selects a font face and size
pdf_set_horiz_scaling -- Sets horizontal scaling of text [deprecated]
pdf_set_info_author -- Deprecated: Fills the author field of the document
pdf_set_info_creator -- Deprecated: Fills the creator field of the document
pdf_set_info_keywords -- Deprecated: Fills the keywords field of the document
pdf_set_info_subject -- Deprecated: Fills the subject field of the document
pdf_set_info_title -- Deprecated: Fills the title field of the document
pdf_set_info -- Fills a field of the document information
pdf_set_leading -- Deprecated: Sets distance between text lines
pdf_set_parameter -- Sets certain parameters
pdf_set_text_matrix -- Deprecated: Sets the text matrix
pdf_set_text_pos -- Sets text position
pdf_set_text_rendering -- Deprecated: Determines how text is rendered
pdf_set_text_rise -- Deprecated: Sets the text rise
pdf_set_value -- Sets certain numerical value
pdf_set_word_spacing -- Deprecated: Sets spacing between words
pdf_setcolor -- Sets fill and stroke color
pdf_setdash -- Sets dash pattern
pdf_setflat -- Sets flatness
pdf_setfont -- Set the current font
pdf_setgray_fill -- Sets filling color to gray value
pdf_setgray_stroke -- Sets drawing color to gray value
pdf_setgray -- Sets drawing and filling color to gray value
pdf_setlinecap -- Sets linecap parameter
pdf_setlinejoin -- Sets linejoin parameter
pdf_setlinewidth -- Sets line width
pdf_setmatrix -- Sets current transformation matrix
pdf_setmiterlimit -- Sets miter limit
pdf_setpolydash -- Deprecated: Sets complicated dash pattern
pdf_setrgbcolor_fill -- Sets filling color to rgb color value
pdf_setrgbcolor_stroke -- Sets drawing color to rgb color value
pdf_setrgbcolor -- Sets drawing and filling color to rgb color value
pdf_show_boxed -- Output text in a box
pdf_show_xy -- Output text at given position
pdf_show -- Output text at current position
pdf_skew -- Skews the coordinate system
pdf_stringwidth -- Returns width of text using current font
pdf_stroke -- Draws line along path
pdf_translate -- Sets origin of coordinate system

pdf_add_annotation

(PHP 3 >= 3.0.12, PHP 4, PECL)

pdf_add_annotation -- Deprecated: Adds annotation

Description

This function is deprecated, use pdf_add_note() instead.

pdf_add_bookmark

(PHP 4 >= 4.0.1, PECL)

pdf_add_bookmark -- Adds bookmark for current page

Description

int pdf_add_bookmark ( resource pdfdoc, string text, int parent, int open )

Add a nested bookmark under parent, or a new top-level bookmark if parent = 0. Returns a bookmark descriptor which may be used as parent for subsequent nested bookmarks. If open = 1, child bookmarks will be folded out, and invisible if open = 0. Parameters parent and open are optional before PHP 4.3.5 or with PDFlib less than 5.

Esempio 1. pdf_add_bookmark() example
<?php // create a new PDF $pdf = pdf_new(); pdf_open_file($pdf); pdf_set_info($pdf, "Author", "Bob Nijman"); // begin a new page pdf_begin_page($pdf, 300, 300); // add a top-level bookmark $bookmark = pdf_add_bookmark($pdf, "People"); // add a nested bookmark pdf_add_bookmark($pdf, "Rasmus", $bookmark); // and some text pdf_set_font($pdf, "Helvetica", 20, "host"); $text = "This is R's page"; $width = pdf_stringwidth($pdf, $text); pdf_set_text_pos($pdf, (300-$width)/2, 100); pdf_show($pdf, $text); // close the page and the PDF pdf_end_page($pdf); pdf_close($pdf); ?>

pdf_add_launchlink

(PHP 4 >= 4.0.5, PECL)

pdf_add_launchlink -- Add a launch annotation for current page

bool pdf_arc ( resource pdfdoc, float x, float y, float r, float alpha, float beta )

Add a counterclockwise circular arc from alpha to beta degrees with center (x; y) and radius r. Actual drawing of the circle is performed by the next stroke or fill operation.

Esempio 1. pdf_arcn() example
<?php // prepare document $pdf = pdf_new(); pdf_open_file($pdf, ""); pdf_begin_page($pdf, 595, 842); // an outlined arc pdf_arc($pdf, 200, 700, 100, 0, 90); pdf_stroke($pdf); // a filled arc pdf_arc($pdf, 200, 700, 50, 0, 90); pdf_fill($pdf); // an outlined and filled arc pdf_setcolor($pdf, "fill", "gray", 0.8); pdf_arc($pdf, 400, 700, 50, 0, 90); pdf_fill_stroke($pdf); // finish document pdf_end_page($pdf); pdf_close($pdf); header("Content-type: application/pdf"); echo pdf_get_buffer($pdf); pdf_delete($pdf); ?>

pdf_arcn

(PHP 4 >= 4.0.5, PECL)

pdf_arcn -- Draws an arc (clockwise)

Description

bool pdf_arcn ( resource pdfdoc, float x, float y, float r, float alpha, float beta )

Add a clockwise circular arc from alpha to beta degrees with center (x; y) and radius r. Actual drawing of the circle is performed by the next stroke or fill operation.

Esempio 1. pdf_arcn() example
<?php // prepare document $pdf = pdf_new(); pdf_open_file($pdf, ""); pdf_begin_page($pdf, 595, 842); // an outlined arcn pdf_arcn($pdf, 200, 700, 100, 0, 90); pdf_stroke($pdf); // a filled arcn pdf_arcn($pdf, 200, 700, 50, 0, 90); pdf_fill($pdf); // an outlined and filled arcn pdf_setcolor($pdf, "fill", "gray", 0.8); pdf_arcn($pdf, 400, 700, 50, 0, 90); pdf_fill_stroke($pdf); // finish document pdf_end_page($pdf); pdf_close($pdf); header("Content-type: application/pdf"); echo pdf_get_buffer($pdf); pdf_delete($pdf); ?>

See also: pdf_arc(), pdf_circle(), pdf_stroke(), pdf_fill() and pdf_fillstroke().

pdf_attach_file

(PHP 4 >= 4.0.5, PECL)

pdf_attach_file -- Adds a file attachment for current page

Description

bool pdf_attach_file ( resource pdfdoc, float llx, float lly, float urx, float ury, string filename, string description, string author, string mimetype, string icon )

Add a file attachment annotation. icon is one of graph, paperclip, pushpin, or tag. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Nota: Only the 'Full' Acrobat software will be able to display these file attachments. All other PDF viewers will either show nothing or display a question mark.

pdf_begin_page

(PHP 3 >= 3.0.6, PHP 4, PECL)

pdf_begin_page -- Starts new page

Description

bool pdf_begin_page ( resource pdfdoc, float width, float height )

Add a new page to the document. Restituisce TRUE in caso di successo, FALSE in caso di fallimento. The width and height are specified in points, which are 1/72 of an inch.

Tabella 1. Common Page Sizes in Points

name	size
A0	2380✗3368
A1	1684✗2380
A2	1190✗1684
A3	842✗1190
A4	595✗842
A5	421✗595
A6	297✗421
B5	501✗709
letter (8.5"✗11")	612✗792
legal (8.5"✗14")	612✗1008
ledger (17"✗11")	1224✗792
11"✗17"	792✗1224

Close the path, and stroke it. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

See also pdf_closepath() and pdf_closepath_fil_stroke().

pdf_closepath

(PHP 3 >= 3.0.6, PHP 4, PECL)

pdf_closepath -- Closes path

Description

pdf_endpath

(PHP 3 >= 3.0.6, PHP 4, PECL)

pdf_endpath -- Deprecated: Ends current path

int pdf_findfont ( resource pdfdoc, string fontname, string encoding, int embed )

Prepare a font for later use with pdf_setfont(). The metrics will be loaded, and if embed is nonzero, the font file will be checked, but not yet used. encoding is one of builtin, macroman, winansi, host, a user-defined encoding name or the name of a CMap. Parameter embed is optional before PHP 4.3.5 or with PDFlib less than 5.

pdf_findfont() returns a font handle or FALSE on error.

Esempio 1. pdf_findfont() example
<?php $font = pdf_findfont($pdf, "Times New Roman", "winansi", 1); if ($font) { pdf_setfont($pdf, $font, 10); } ?>

pdf_get_buffer

(PHP 4 >= 4.0.5, PECL)

pdf_get_buffer -- Fetch the buffer containing the generated PDF data

Description

string pdf_get_buffer ( resource pdfdoc )

bool pdf_moveto ( resource pdfdoc, float x, float y )

Set the current point to (x, y. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Nota: The current point for graphics and the current text output position are maintained separately. See pdf_set_text_pos() to set the text output position.

The following example shows how to create a pdf document in memory and how to output it correctly.
Esempio 1. Creating a PDF document in memory
<?php $pdf = pdf_new(); pdf_open_file($pdf); pdf_begin_page($pdf, 595, 842); pdf_set_font($pdf, "Times-Roman", 30, "host"); pdf_set_value($pdf, "textrendering", 1); pdf_show_xy($pdf, "A PDF document created in memory!", 50, 750); pdf_end_page($pdf); pdf_close($pdf); $data = pdf_get_buffer($pdf); header("Content-type: application/pdf"); header("Content-disposition: inline; filename=test.pdf"); header("Content-length: " . strlen($data)); echo $data; ?>

pdf_open_gif

(PHP 3 >= 3.0.7, PHP 4, PECL)

pdf_open_gif -- Deprecated: Opens a GIF image

bool pdf_set_value ( resource pdfdoc, string key, float value )

Set the value of some PDFlib parameter with float type. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

pdf_set_word_spacing

(PHP 3 >= 3.0.6, PHP 4, PECL)

pdf_set_word_spacing -- Deprecated: Sets spacing between words

Description

This function is deprecated, use pdf_set_value() instead.

pdf_setcolor

(PHP 4 >= 4.0.5, PECL)

pdf_setcolor -- Sets fill and stroke color

Description

bool pdf_setcolor ( resource pdfdoc, string type, string colorspace, float c1, float c2, float c3, float c4 )

Set the current color space and color. Restituisce TRUE in caso di successo, FALSE in caso di fallimento. The parameter type can be fill, stroke or both to specify that the color is set for filling, stroking or both filling and stroking. The parameter colorspace can be gray, rgb, cmyk, spot or pattern. The parameters c1, c2, c3 and c4 represent the color components for the color space specified by colorspace. Except as otherwise noted, the color components are floating-point values that range from 0 to 1. Parameters c2, c3 and c4 are optional before PHP 4.3.5 or with PDFlib less than 5.

For gray only c1 is used.

For rgb parameters c1, c2, and c3 specify the red, green and blue values respectively.

<?php
// Set fill and stroke colors to white.
pdf_setcolor($pdf, "both", "rgb", 1, 1, 1);
?>

For cmyk, parameters c1, c2, c3, and c4 are the cyan, magenta, yellow and black values, respectively.

<?php
// Set fill and stroke colors to black.
pdf_setcolor($pdf, "both", "cmyk", 0, 0, 0, 1);
?>

bool pdf_setgray_fill ( resource pdfdoc, float gray )

Set the current fill color to a gray value between 0 and 1 inclusive. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Nota: PDFlib V4.0: Deprecated, use pdf_setcolor() instead.

pdf_setgray_stroke

(PHP 3 >= 3.0.6, PHP 4, PECL)

pdf_setgray_stroke -- Sets drawing color to gray value

Description

bool pdf_setgray_stroke ( resource pdfdoc, float gray )

Set the current stroke color to a gray value between 0 and 1 inclusive. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Nota: PDFlib V4.0: Deprecated, use pdf_setcolor() instead.

pdf_setgray

(PHP 3 >= 3.0.6, PHP 4, PECL)

pdf_setgray -- Sets drawing and filling color to gray value

Description

bool pdf_setgray ( resource pdfdoc, float gray )

Set the current fill and stroke color. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Nota: PDFlib V4.0: Deprecated, use pdf_setcolor() instead.

(PHP 3 >= 3.0.6, PHP 4, PECL)

pdf_setrgbcolor_fill -- Sets filling color to rgb color value

Description

bool pdf_setrgbcolor_fill ( resource pdfdoc, float red_value, float green_value, float blue_value )

Set the current fill color to the supplied RGB values. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Nota: PDFlib V4.0: Deprecated, use pdf_setcolor() instead.

pdf_setrgbcolor_stroke

(PHP 3 >= 3.0.6, PHP 4, PECL)

pdf_setrgbcolor_stroke -- Sets drawing color to rgb color value

Description

bool pdf_setrgbcolor_stroke ( resource pdfdoc, float red_value, float green_value, float blue_value )

Set the current stroke color to the supplied RGB values. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Nota: PDFlib V4.0: Deprecated, use pdf_setcolor() instead.

pdf_setrgbcolor

(PHP 3 >= 3.0.6, PHP 4, PECL)

pdf_setrgbcolor -- Sets drawing and filling color to rgb color value

Description

bool pdf_setrgbcolor ( resource pdfdoc, float red_value, float green_value, float blue_value )

Set the current fill and stroke color to the supplied RGB values. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Nota: PDFlib V4.0: Deprecated, use pdf_setcolor() instead.

pdf_show_boxed

(PHP 4, PECL)

pdf_show_boxed -- Output text in a box

Description

int pdf_show_boxed ( resource pdfdoc, string text, float left, float top, float width, float height, string mode, string feature )

float pdf_stringwidth ( resource pdfdoc, string text, int font, float size )

Returns the width of text using the parameters font and size. Please note that font is a font handle returned by pdf_findfont(). Parameters font and size are optional before PHP 4.3.5 or with PDFlib less than 5. If they are not specified, the font set by pdf_setfont() is used.

Nota: Both the font and size parameters must be used together.

pdf_stroke

(PHP 3 >= 3.0.6, PHP 4, PECL)

pdf_stroke -- Draws line along path

Description

bool pdf_stroke ( resource pdfdoc )

Stroke the path with the current color and line width, and clear it. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

pdf_translate

(PHP 3 >= 3.0.6, PHP 4, PECL)

pdf_translate -- Sets origin of coordinate system

Description

bool pdf_translate ( resource pdfdoc, float tx, float ty )

Translate the origin of the coordinate system.

CX. PDO Functions

Introduzione

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.

Installazione

PHP 5.1 and up on Unix systems

If you're running a PHP 5.1 release, PDO is included in the distribution; it will be automatically enabled when you run configure. It is recommended that you build PDO as a shared extension, as this will allow you to take advantage of updates that are made available via PECL. The recommended configure line for building PHP with PDO support should enable zlib support (for the pear installer) as well. You may also 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.
./configure --with-zlib --enable-pdo=shared
After installing PDO as a shared module, you must edit your php.ini file 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 the extensions statically, you can skip this step.
extension=pdo.so
Having PDO as a shared module will allow you to run pear upgrade pdo as new versions of PDO are published, without forcing you to rebuild the whole of PHP. Note that if you do this, you also need to upgrade your database specific PDO drivers at the same time.

PHP 5.0 and up on Unix systems

PDO is available as a PECL extension from http://pecl.php.net/package/pdo. Installation can be performed via the pear tool; this is enabled by default when you configure PHP. You should ensure that PHP was configured --with-zlib in order for pear to be able to handle the compressed package files.
Run the following command to download, build, and install the latest stable version of PDO:
pear install pdo
If PDO is still in beta (and at the time of writing, it is), you will need to tell the pear tool that it's ok to fetch the beta package. Instead of running the command above, run the following:
pear install pdo-beta
The pear command automatically installs the PDO module into your PHP extensions directory. To enable the PDO extension on Linux or Unix operating systems, you must add the following line to php.ini:
extension=pdo.so
For more information about building PECL packages, consult the PECL installation section of the manual.

Windows users running PHP 5.1 and up

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

Next, choose the other DB 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_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.

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

Tabella 1. PDO Configuration Options

Name	Default	Changeable	Changelog
pdo.dsn.*		`php.ini` only

Per maggiori dettagli sulle costanti PHP_INI_* vedere Appendice G.

Breve descrizione dei parametri di configurazione.

pdo.dsn.* string: Defines DSN alias. See PDO::__construct for thorough explanation.

PDO Drivers

The following drivers currently implement the PDO interface:

Driver name	Supported databases
PDO_DBLIB	FreeTDS / Microsoft SQL Server / Sybase
PDO_FIREBIRD	Firebird/Interbase 6
PDO_MYSQL	MySQL 3.x/4.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

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).

Esempio 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().

Esempio 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(); } ?>

Avvertimento

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.

Esempio 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.

Esempio 4. Persistent connections
<?php $dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass, array( PDO::ATTR_PERSISTENT => true )); ?>

Nota: 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 should be able to 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.

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.

Avvertimento

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.

Esempio 5. 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"; $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. In truth, this isn't 100% correct, but it is a good-enough introduction, if you've never heard of transactions before.

Prepared statements and stored procedures

Many of the more mature databases support the concept of prepared statements. What are they? You can think of them as a kind of compiled template for the SQL that you want 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 it's plan for executing the query. For complex queries this process can take up enough time that it will noticably slow down your application if you need to repeat the same query many times with different parameters. By using a prepared statement you avoid repeating the analyze/compile/optimize cycle. In short, prepared statements use fewer resources and thus run faster.
The parameters to prepared statements don't need to be quoted; the driver handles it for you. If your application exclusively uses prepared statements, you can be sure that no SQL injection will occur. (However, if you're still building up other parts of the query based on untrusted input, you're still at risk).

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 you will be able to use the same data access paradigm regardless of the capabilities of the database.

Esempio 6. 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(); ?>

Esempio 7. 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(); ?>

Esempio 8. 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, you 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 you must know how large a given parameter might be when you bind it. If the value turns out to be larger than the size you suggested, an error is raised.

Esempio 9. 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"; ?>

You 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.

Esempio 10. 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"; ?>

Errors and error handling

PDO offers you a choice of 3 different error handling strategies, to fit your style of application development.

PDO::ERRMODE_SILENT
This 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_WARNING
In 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_EXCEPTION
In 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.

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.

Esempio 11. 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); ?>

Esempio 12. 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); $stmt->execute(); ?>

Classi predefinite

PDO

Represents a connection between PHP and a database server.

Costruttori

PDO - constructs a new PDO object

Metodi

beginTransaction - begins a transaction
commit - commits a transaction
errorCode - retrieves an error code, if any, from the database
errorInfo - retrieves an array of error information, if any, from the database
exec - issues an SQL statement and returns the number of affected rows
getAttribute - retrieves a database connection attribute
lastInsertId - retrieves the value of the last row that was inserted into a table
prepare - prepares an SQL statement for execution
query - issues an SQL statement and returns a result set
quote - returns a quoted version of a string for use in SQL statements
rollBack - roll back a transaction
setAttribute - sets a database connection attribute

PDOStatement

Represents a prepared statement and, after the statement is executed, an associated result set.

Metodi

bindColumn - binds a PHP variable to an output column in a result set
bindParam - binds a PHP variable to a parameter in the prepared statement
bindValue - binds a value to a parameter in the prepared statement
closeCursor - closes the cursor, allowing the statement to be executed again
columnCount - returns the number of columns in the result set
errorCode - retrieves an error code, if any, from the statement
errorInfo - retrieves an array of error information, if any, from the statement
execute - executes a prepared statement
fetch - fetches a row from a result set
fetchAll - fetches an array containing all of the rows from a result set
fetchColumn - returns the data from a single column in a result set
getAttribute - retrieves a PDOStatement attribute
getColumnMeta - retrieves metadata for a column in the result set
nextRowset - retrieves the next rowset (result set)
rowCount - returns the number of rows that were affected by the execution of an SQL statement
setAttribute - sets a PDOStatement attribute
setFetchMode - sets the fetch mode for a PDOStatement

PDOException

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.

Esempio 13. The PDOException class

<?php
class PDOException extends Exception
{
    public $errorInfo = null;    // corresponds to PDO::errorInfo()
                                 // or PDOStatement::errorInfo()
    protected $message;          // textual error message
                                 // use Exception::getMessage() to access it
    protected $code;             // SQLSTATE error code
                                 // use Exception::getCode() to access it
}
?>

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

Avvertimento

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_LAZY creates 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_ASSOC returns only a single value per column name.

PDO::FETCH_NAMED (integer)

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.

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_CLASSTYPE (integer)

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_FWDONLY and PDO::CURSOR_SCROLL. Stick with PDO::CURSOR_FWDONLY unless you know that you need a scrollable cursor.

PDO::ATTR_DRIVER_NAME (string)

Returns the name of the driver.

Esempio 14. 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_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::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_WARNING message 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::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.

Sommario
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::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::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::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::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

PDO::beginTransaction

(no version information, might be only in CVS)

PDO::beginTransaction -- Initiates a transaction

Descrizione

bool PDO::beginTransaction ( void )

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.

Esempi

Esempio 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 */ ?>

Vedere anche:

PDO::commit()

PDO::rollBack()

PDO::commit

(no version information, might be only in CVS)

PDO::commit -- Commits a transaction

Descrizione

bool PDO::commit ( void )

Commits a transaction, returning the database connection to autocommit mode until the next call to PDO::beginTransaction() starts a new transaction.

Esempi

Esempio 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 */ ?>

Vedere anche:

PDO::beginTransaction()

PDO::rollBack()

PDO::__construct

(no version information, might be only in CVS)

PDO::__construct -- Creates a PDO instance representing a connection to a database

Descrizione

PDO PDO::__construct ( string dsn [, string username [, string password [, array driver_options]]] )

Creates a PDO instance to represent a connection to the requested database.

Elenco dei parametri

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 dsn parameter supports three different methods of specifying the arguments required to create a database connection:

Driver invocation

dsn contains the full DSN.

URI invocation

dsn consists of uri: 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

dsn consists of a name name that maps to pdo.dsn.name in php.ini defining the DSN string.

Nota: 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.

Valori restituiti

Returns a PDO object on success.

Eccezioni

PDO::construct() throws a PDOException if the attempt to connect to the requested database fails.

Esempi

Esempio 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(); } ?>

Esempio 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(); } ?>

Esempio 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

(no version information, might be only in CVS)

PDO::errorCode -- Fetch the SQLSTATE associated with the last operation on the database handle

Descrizione

int PDO::errorCode ( void )

Valori restituiti

Returns a SQLSTATE, a five-character alphanumeric identifier defined in the ANSI SQL-92 standard. Briefly, an SQLSTATE consists of a two-character class value followed by a three-character 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.

Esempi

Esempio 1. Retrieving a 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(); ?>
Il precedente esempio visualizzerà:
PDO::errorCode(): 42S02

Vedere anche:

PDO::errorInfo()

PDOStatement::errorCode()

PDOStatement::errorInfo()

PDO::errorInfo

(no version information, might be only in CVS)

PDO::errorInfo -- Fetch extended error information associated with the last operation on the database handle

Descrizione

array PDO::errorInfo ( void )

Valori restituiti

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-character alphanumeric identifier defined in the ANSI SQL standard).
1	Driver-specific error code.
2	Driver-specific error message.

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.

Esempi

Esempio 1. Displaying errorInfo() fields for a PDO_ODBC connection to a DB2 database
<?php /* Provoke an error -- the BONES table does not exist */ $err = $dbh->prepare('SELECT skull FROM bones'); $err->execute(); echo "\nPDO::errorInfo():\n"; print_r($err->errorInfo()); ?>
Il precedente esempio visualizzerà:
PDO::errorInfo(): Array ( [0] => 42S02 [1] => -204 [2] => [IBM][CLI Driver][DB2/LINUX] SQL0204N "DANIELS.BONES" is an undefined name. SQLSTATE=42704 )

Vedere anche:

PDO::errorCode()

PDOStatement::errorCode()

PDOStatement::errorInfo()

PDO::exec

(no version information, might be only in CVS)

PDO::exec -- Execute an SQL statement and return the number of affected rows

Descrizione

int PDO::exec ( string 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().

Elenco dei parametri

statement: The SQL statement to prepare and execute.

Valori restituiti

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.

Avvertimento

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($db->errorInfo()); ?>

Esempi

Esempio 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"); ?>
Il precedente esempio visualizzerà:
Deleted 1 rows.

Vedere anche:

PDO::prepare()

PDO::query()

PDOStatement::execute()

PDO::getAttribute

(no version information, might be only in CVS)

PDO::getAttribute -- Retrieve a database connection attribute

Descrizione

mixed PDO::getAttribute ( int attribute )

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.

Elenco dei parametri

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

Valori restituiti

A successful call returns the value of the requested PDO attribute. An unsuccessful call returns null.

Esempi

Esempio 1. Retrieving database connection attributes
<?php $conn = new PDO('odbc:sample', 'db2inst1', 'ibmdb2'); print "\nPDO::ATTR_AUTOCOMMIT: "; print $conn->getAttribute(PDO::ATTR_AUTOCOMMIT); print "\nPDO::ATTR_ERRMODE: "; print $conn->getAttribute(PDO::ATTR_ERRMODE); print "\nPDO::ATTR_CASE: "; print $conn->getAttribute(PDO::ATTR_CASE); print "\nPDO::ATTR_CLIENT_VERSION: "; print $conn->getAttribute(PDO::ATTR_CLIENT_VERSION); print "\nPDO::ATTR_CONNECTION_STATUS: "; print $conn->getAttribute(PDO::ATTR_CONNECTION_STATUS); print "\nPDO::ATTR_ORACLE_NULLS: "; print $conn->getAttribute(PDO::ATTR_ORACLE_NULLS); print "\nPDO::ATTR_PERSISTENT: "; print $conn->getAttribute(PDO::ATTR_PERSISTENT); print "\nPDO::ATTR_PREFETCH: "; print $conn->getAttribute(PDO::ATTR_PREFETCH); print "\nPDO::ATTR_SERVER_INFO: "; print $conn->getAttribute(PDO::ATTR_SERVER_INFO); print "\nPDO::ATTR_SERVER_VERSION: "; print $conn->getAttribute(PDO::ATTR_SERVER_VERSION); print "\nPDO::ATTR_TIMEOUT: "; print $conn->getAttribute(PDO::ATTR_TIMEOUT); ?>

Vedere anche:

PDO::setAttribute()

PDOStatement::getAttribute()

PDOStatement::setAttribute()

PDO::getAvailableDrivers

(no version information, might be only in CVS)

PDO::getAvailableDrivers -- Return an array of available PDO drivers

Descrizione

array PDO::getAvailableDrivers ( void )

This function returns all currently available PDO drivers which can be used in DSN parameter of PDO::__construct(). This is a static method.

Valori restituiti

PDO::getAvailableDrivers() returns an array of PDO driver names. If no drivers are available, it returns an empty array.

Esempi

Esempio 1. A PDO::getAvailableDrivers() example
<?php print_r(PDO::getAvailableDrivers()); ?>
Il precedente esempio visualizzerà qualcosa simile a:
Array ( [0] => mysql [1] => sqlite )

PDO::lastInsertId

(no version information, might be only in CVS)

PDO::lastInsertId -- Returns the ID of the last inserted row or sequence value

Description

string PDO::lastInsertId ( [string name] )

Returns the ID of the last inserted row, or the last value from a sequence object, depending on the underlying driver.

Nota: This method may not return a meaningful/consistent result across different PDO drivers, because the underlying database may not even support the notion of auto-increment fields or sequences.

Elenco dei parametri

name: Name of the sequence object from which the ID should be returned.

Valori restituiti

If a sequence name was not specified for the name parameter, PDOStatement::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, PDOStatement::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

(no version information, might be only in CVS)

PDO::prepare -- Prepares a statement for execution and returns a statement object

Descrizione

PDOStatement PDO::prepare ( string statement [, array driver_options] )

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.

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.

Elenco dei parametri

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.

Valori restituiti

If the database server successfully prepares the statement, PDO::prepare() returns a PDOStatement object.

Esempi

Esempio 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(); ?>

Esempio 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(); ?>

Vedere anche:

PDO::exec()

PDO::query()

PDOStatement::execute()

PDO::query

(no version information, might be only in CVS)

PDO::query -- Executes an SQL statement, returning a result set as a PDOStatement object

Descrizione

PDOStatement PDO::query ( string statement )

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().

Elenco dei parametri

statement: The SQL statement to prepare and execute.

Valori restituiti

PDO::query() returns a PDOStatement object.

Esempi

Esempio 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, colour, calories FROM fruit ORDER BY name'; foreach ($conn->query($sql) as $row) { print $row['NAME'] . "\t"; print $row['COLOUR'] . "\t"; print $row['CALORIES'] . "\n"; } } ?>
Il precedente esempio visualizzerà:
apple red 150 banana yellow 250 kiwi brown 75 lemon yellow 25 orange orange 300 pear green 150 watermelon pink 90

Vedere anche:

PDO::exec()

PDO::prepare()

PDOStatement::execute()

PDO::quote

(no version information, might be only in CVS)

PDO::quote -- Quotes a string for use in a query.

Descrizione

string PDO::quote ( string string [, int parameter_type] )

PDO::quote() places quotes around the input string and escapes and single quotes 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 a SQL statement. Prepared statements with bound parameters are not only more portable, more convenient, and vastly more secure, but are often much faster than interpolating user input into slight variations on the same basic SQL statement.

Not all PDO drivers implement this method (notably PDO_ODBC). Consider using prepared statements instead.

Elenco dei parametri

string: The string to be quoted.
parameter_type: Provides a data type hint for drivers that have alternate quoting styles. The default value is PDO_PARAM_STR.

Valori restituiti

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.

Esempi

Esempio 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"; ?>
Il precedente esempio visualizzerà:
Unquoted string: Nice Quoted string: 'Nice'

Esempio 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"; ?>
Il precedente esempio visualizzerà:
Unquoted string: Naughty ' string Quoted string: 'Naughty '' string'

Esempio 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"; ?>
Il precedente esempio visualizzerà:
Unquoted string: Co'mpl''ex "st'"ring Quoted string: 'Co''mpl''''ex "st''"ring'

Vedere anche:

PDO::prepare()

PDOStatement::execute()

PDO::rollBack

(no version information, might be only in CVS)

PDO::rollBack -- Rolls back a transaction

Descrizione

bool PDO::rollBack ( void )

Rolls back the current transaction, as initiated by PDO::beginTransaction(). It is an error to call this method 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.

Esempi

Vedere anche:

PDO::beginTransaction()

PDO::commit()

PDO::setAttribute

(no version information, might be only in CVS)

PDO::setAttribute -- Set an attribute

Description

bool PDO::setAttribute ( int attribute, mixed value )

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.

PDOStatement::bindColumn

(no version information, might be only in CVS)

PDOStatement::bindColumn -- Bind a column to a PHP variable

Descrizione

bool PDOStatement::bindColumn ( mixed column, mixed &param [, int type] )

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.

Nota: Since information about the columns is not always available to PDO until the statement is executed, portable applications should call this function after PDO::execute().

Elenco dei parametri

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.

Esempi

Esempio 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); ?>
Il precedente esempio visualizzerà:
apple red 150 banana yellow 175 kiwi green 75 orange orange 150 mango red 200 strawberry red 25

Vedere anche:

PDOStatement::execute()

PDOStatement::fetch()

PDOStatement::fetchAll()

PDOStatement::fetchColumn()

PDOStatement::bindParam

(no version information, might be only in CVS)

PDOStatement::bindParam -- Binds a parameter to the specified variable name

Descrizione

bool PDOStatement::bindParam ( mixed parameter, mixed &variable [, int data_type [, 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.

Elenco dei parametri

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_type parameter.
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

Esempi

Esempio 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();
?>

Esempio 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();
?>

Esempio 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");
?>

Vedere anche:

PDO::prepare()

PDOStatement::execute()

PDOStatement::bindValue()

PDOStatement::bindValue

(no version information, might be only in CVS)

PDOStatement::bindValue -- Binds a value to a parameter

Descrizione

bool PDOStatement::bindValue ( mixed parameter, mixed value [, int data_type] )

Binds a value to a corresponding named or question mark placeholder in the SQL statement that was use to prepare the statement.

Elenco dei parametri

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.

Esempi

Esempio 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();
?>

Esempio 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();
?>

Vedere anche:

PDO::prepare()

PDOStatement::execute()

PDOStatement::bindParam()

PDOStatement::closeCursor

(no version information, might be only in CVS)

PDOStatement::closeCursor -- Closes the cursor, enabling the statement to be executed again.

Descrizione

bool PDOStatement::closeCursor ( void )

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); ?>

Esempi

Esempio 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 */ $stmt = $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(); ?>

Vedere anche:

PDOStatement::execute()

PDOStatement::columnCount

(no version information, might be only in CVS)

PDOStatement::columnCount -- Returns the number of columns in the result set

Descrizione

int PDOStatement::columnCount ( void )

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().

Valori restituiti

Returns the number of columns in the result set represented by the PDOStatement object. If there is no result set, PDOStatement::columnCount() returns 0.

Esempi

Esempio 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"); ?>
Il precedente esempio visualizzerà:
Before execute(), result set has 0 columns (should be 0) After execute(), result set has 2 columns (should be 2)

Vedere anche:

PDO::prepare()

PDOStatement::execute()

PDOStatement::rowCount()

PDOStatement::errorCode

(no version information, might be only in CVS)

PDOStatement::errorCode -- Fetch the SQLSTATE associated with the last operation on the statement handle

Descrizione

int PDOStatement::errorCode ( void )

Valori restituiti

Identical to PDO::errorCode(), except that PDOStatement::errorCode() only retrieves error codes for operations performed with PDOStatement objects.

Esempi

Esempio 1. Retrieving a 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(); ?>
Il precedente esempio visualizzerà:
PDOStatement::errorCode(): 42S02

Vedere anche:

PDO::errorCode()

PDO::errorInfo()

PDOStatement::errorInfo()

PDOStatement::errorInfo

(no version information, might be only in CVS)

PDOStatement::errorInfo -- Fetch extended error information associated with the last operation on the statement handle

Descrizione

array PDOStatement::errorInfo ( void )

Valori restituiti

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-character alphanumeric identifier defined in the ANSI SQL standard).
1	Driver-specific error code.
2	Driver-specific error message.

Esempi

Esempio 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); ?>
Il precedente esempio visualizzerà:
PDOStatement::errorInfo(): Array ( [0] => 42S02 [1] => -204 [2] => [IBM][CLI Driver][DB2/LINUX] SQL0204N "DANIELS.BONES" is an undefined name. SQLSTATE=42704 )

Vedere anche:

PDO::errorCode()

PDO::errorInfo()

PDOStatement::errorCode()

PDOStatement::execute

(no version information, might be only in CVS)

PDOStatement::execute -- Executes a prepared statement

Descrizione

bool PDOStatement::execute ( [array 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

Esempi

Esempio 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();
?>

Esempio 2. Execute a prepared statement with an array of insert values

<?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));
?>

Esempio 3. 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();
?>

Vedere anche:

PDO::prepare()

PDOStatement::bindParam()

PDOStatement::fetch()

PDOStatement::fetchAll()

PDOStatement::fetchColumn()

PDOStatement::fetch

(no version information, might be only in CVS)

PDOStatement::fetch -- Fetches the next row from a result set

Descrizione

mixed PDOStatement::fetch ( [int fetch_style [, int cursor_orientation [, int cursor_offset]]] )

Fetches a row from a result set associated with a PDOStatement object.

Elenco dei parametri

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 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 column number as returned in your result set
PDO::FETCH_BOUND: returns TRUE and assigns the values of the columns in your result set to the PHP variables to which they were bound with the PDOStatement::bindParam() method
PDO::FETCH_LAZY: combines PDO::FETCH_BOTH and PDO::FETCH_OBJ, creating the object variable names as they are accessed
PDO::FETCH_OBJ: returns an anonymous object with property names that correspond to the column names returned in your result set
PDO::FETCH_NUM: returns an array indexed by column number as returned in your result set, starting at column 0

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.

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.

Esempi

Esempio 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"); ?>
Il precedente esempio visualizzerà:
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

Esempio 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); ?>
Il precedente esempio visualizzerà:
Reading forwards: 21 10 5 16 0 5 19 20 10 Reading backwards: 19 20 10 16 0 5 21 10 5

Vedere anche:

PDO::query()

PDOStatement::fetchAll()

PDOStatement::fetchColumn()

PDOStatement::prepare()

PDOStatement::setFetchMode()

PDOStatement::fetchAll

(no version information, might be only in CVS)

PDOStatement::fetchAll -- Returns an array containing all of the result set rows

Descrizione

array PDOStatement::fetchAll ( [int fetch_style [, int column_index]] )

Elenco dei parametri

fetch_style

Controls the contents of the returned array as documented in PDOStatement::fetch(). Defaults to PDO::FETCH_BOTH.

To return an array consisting of all values of a single column from the result set, specify PDO::FETCH_COLUMN.

To fetch only the unique values of a single column from the result set, bitwise-OR PDO::FETCH_COLUMN with PDO::FETCH_UNIQUE.

To return an associative array grouped by the values of a specified column, bitwise-OR PDO::FETCH_COLUMN with PDO::FETCH_GROUP.

column_index

Returns the indicated 0-indexed column when the value of fetch_style is PDO::FETCH_COLUMN. Defaults to 0.

Valori restituiti

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 SORT BY clauses in SQL to restrict results before retrieving and processing them with PHP.

Esempi

Esempio 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); ?>
Il precedente esempio visualizzerà:
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 ) )

Esempio 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); ?>
Il precedente esempio visualizzerà:
Array(3) ( [0] => string(5) => apple [1] => string(4) => pear [2] => string(10) => watermelon )

Esempio 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('apple', 'green'); $insert->execute('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)); ?>
Il precedente esempio visualizzerà:
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" } }

Vedere anche:

PDO::query()

PDOStatement::fetch()

PDOStatement::fetchColumn()

PDOStatement::prepare()

PDOStatement::setFetchMode()

PDOStatement::fetchColumn

(no version information, might be only in CVS)

PDOStatement::fetchColumn -- Returns a single column from the next row of a result set

Descrizione

string PDOStatement::fetchColumn ( [int column_number] )

Returns a single column from the next row of a result set.

Elenco dei parametri

column_number: Number of the column you wish to retrieve from the row. If no value is supplied, PDOStatement::fetchColumn() fetches the first column.

Valori restituiti

PDOStatement::fetchColumn() returns a single column in the next row of a result set.

Avvertimento

There is no way to return another column from the same row if you use PDOStatement::fetchColumn() to retrieve data.

Esempi

Esempio 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("$result\n"); $result = $sth->fetchColumn(); print("$result\n"); ?>
Il precedente esempio visualizzerà:
Fetch the first column from the next row in the result set: lemon orange

Vedere anche:

PDO::query()

PDOStatement::fetch()

PDOStatement::fetchAll()

PDOStatement::prepare()

PDOStatement::setFetchMode()

PDOStatement::getAttribute

(no version information, might be only in CVS)

PDOStatement::getAttribute -- Retrieve a statement attribute

Descrizione

mixed PDOStatement::getAttribute ( int attribute )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Vedere anche:

PDO::getAttribute()

PDO::setAttribute()

PDOStatement::setAttribute()

PDOStatement::getColumnMeta

(no version information, might be only in CVS)

PDOStatement::getColumnMeta -- Returns metadata for a column in a result set

Descrizione

mixed PDOStatement::getColumnMeta ( int column )

Avvertimento

Retrieves the metadata for a 0-indexed column in a result set as an associative array.

Avvertimento

Not all PDO drivers support PDOStatement::getColumnMeta().

Elenco dei parametri

column: The 0-indexed column in the result set.

Valori restituiti

Returns an associative array containing the following values representing the metadata for a single column:

Tabella 1. Column metadata

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.
`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.

Esempi

Esempio 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); ?>
Il precedente esempio visualizzerà:
array(6) { ["native_type"]=> string(7) "integer" ["flags"]=> array(0) { } ["name"]=> string(8) "COUNT(*)" ["len"]=> int(-1) ["precision"]=> int(0) ["pdo_type"]=> int(2) }

Vedere anche:

PDOStatement::columnCount()

PDOStatement::rowCount()

PDOStatement::nextRowset

(no version information, might be only in CVS)

PDOStatement::nextRowset -- Advances to the next rowset in a multi-rowset statement handle

Descrizione

bool PDOStatement::nextRowset ( void )

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.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 1. Fetching multiple rowsets returned from a stored procedure
The following example shows how to call a stored procedure, MULTIPLE_RESULTS, 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"; } ?>
Il precedente esempio visualizzerà:
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

Vedere anche:

PDOStatement::columnCount()

PDOStatement::execute()

PDOStatement::getColumnMeta()

PDOStatement::query()

PDOStatement::rowCount

(no version information, might be only in CVS)

PDOStatement::rowCount -- Returns the number of rows affected by the last SQL statement

Descrizione

int PDOStatement::rowCount ( void )

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.

Esempi

Esempio 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"); ?>
Il precedente esempio visualizzerà:
Deleted 9 rows.

Esempio 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; ?>
Il precedente esempio visualizzerà:
apple banana orange pear

Vedere anche:

PDOStatement::columnCount()

PDOStatement::fetchColumn()

PDOStatement::query()

PDOStatement::setAttribute

(no version information, might be only in CVS)

PDOStatement::setAttribute -- Set a statement attribute

Descrizione

bool PDOStatement::setAttribute ( int attribute, mixed value )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Vedere anche:

PDO::getAttribute()

PDO::setAttribute()

PDOStatement::getAttribute()

PDOStatement::setFetchMode

(no version information, might be only in CVS)

PDOStatement::setFetchMode -- Set the default fetch mode for this statement

Descrizione

bool PDOStatement::setFetchMode ( int mode )

Elenco dei parametri

mode: The fetch mode must be one of the PDO::FETCH_* constants.

Valori restituiti

Returns 1 on success or FALSE on failure.

Esempi

Esempio 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(); } ?>
Il precedente esempio visualizzerà:
apple red 150 banana yellow 250 orange orange 300 kiwi brown 75 lemon yellow 25 pear green 150 watermelon pink 90

CXI. PHP Opzioni&Informazioni

Introduzione

Queste funzioni permettono di accedere a diverse informazioni sul PHP stesso, come la configurazione di runtime, il moduli caricati, la versione e molto altro. Si troveranno anche funzioni per impostare le opzioni di runtime del PHP. Probabilmente la più nota tra queste è - phpinfo() -.

Requisiti

Non sono necessarie librerie esterne per utilizzare questo modulo.

Installazione

Non è necessaria nessuna installazione per usare queste funzioni, esse fanno parte del core di PHP.

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

Tabella 1. Parametri di configurazione per PHP Opzioni/informazioni

Nome	Default	Modificabile
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
max_execution_time	"30"	PHP_INI_ALL
max_input_time	"60"	PHP_INI_ALL
magic_quotes_gpc	"1"	PHP_INI_PERDIR\|PHP_INI_SYSTEM
magic_quotes_runtime	"0"	PHP_INI_ALL

Per maggiori dettagli e per le definizioni delle costanti PHP_INI_* fare riferimento a ini_set().

Breve descrizione dei parametri di configurazione.

assert.active boolean

Abilita l'analisi degli assert().

assert.bail boolean

Termina uno script a fronte di un assert fallito.

assert.warning boolean

Invia un PHP warning per ogni asserzione fallita.

assert.callback string

Funzione utente da richiamare a fronte di un assert fallito

assert.quiet_eval boolean

Utilizzare questo parametro di error_reporting() durante l'analisi dei un'asserzione. Se è abilitato, non sono visualizzati gli errori (error_reporting(0)) durante il parsing di una asserzione. Se disabilitato, gli errori saranno visualizzati in base all'impostazione di error_reporting().

enable_dl boolean

Questa direttiva è utile soltanto nella versione di PHP attiva come modulo di Apache. Essa permette di caricare in modo dinamico le estensioni di PHP potendo impostare dl() on oppure off in base al server virtuale o per directory.

La ragione principale per disabilitare il caricamento dinamico dei moduli è la sicurezza. Con il caricamento dinamico è possibile ignorare tutte le restrizioni open_basedir. Per default il caricamento dinamico è attivo tranne quando si utilizza il modalità sicura. In modalità sicura, è sempre impossibile utilizzare dl().

max_execution_time integer

Questo parametro imposta il tempo massimo in secondi concessi ad uno script per l'esecuzione prima di essere interrotto dal parser. Questo aiuta a prevenire che script scritti male blocchino il server. Per default è impostato a 30.

Il tempo massimo di esecuzione non è condizionato dalle chiamate di sistema, dalle operazioni sugli stream, eccetera. Vedere la funzione set_time_limit() per maggiori dettagli.

Non si può cambiare questo parametro con ini_set() quando il PHP gira in modalità sicura. L'unico modo è di disabilitare il safe mode oppure di cambiare il limite di tempo nel php.ini.

Anche il server web ha i propri timeout. Ad esempio Apache ha un proprio parametro Timeout, IIS ha una funzione di timeout sugli script CGI, entrambi con default 300 secondi. Vedere la documentazione del server web per maggiori dettagli.

max_input_time integer

Impostail tempo massimo in secondi concesso ad uno script per ricevere i dati di input, tipo POST, GET e upload di file. Il valore di default è 60.

magic_quotes_gpc boolean

Imposta il parametro magic_quote per GPC (Get/Post/Cookie). Quando magic_quote è impostato a on, tutti i ' (apici singoli), " (doppi apici), \ (backslash) e NUL sono vengono preceduti in automatico dal backslash.

Nota: Se il parametro magic_quotes_sybase è impostato a ON, questo è prioritario rispetto a magic_quotes_gpc. Avere entrambi i parametri attivi significa che soltanto gli apici singoli sono preceduti dal carattere di escape come ''. Doppi apici, backslash, e NUL non vengono toccati.

Vedere anche get_magic_quotes_gpc()

magic_quotes_runtime boolean

Se si abilita magic_quotes_runtime, diverse funzioni che restituiscono dati da ogni tipo di fonte esterna, compresi i database ed i file di testo, avranno gli apici preceduti dal backslash. Se è anche attivato magic_quotes_sybase, soltanto l'apice singolo sarà preceduto dal carattere di escape costituito da un apice singolo anzichè il backslash.

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

Le costanti qui elencate sono sempre disponibili in quanto parte del core di PHP.

Tabella 2. Costanti predefinite per phpcredits()

Costante	Valore	Descrizione
CREDITS_GROUP	1	Lista degli sviluppatori principali
CREDITS_GENERAL	2	Lista generale: design e progetto del linguaggio, autori del PHP e del modulo SAPI.
CREDITS_SAPI	4	Lista delle API server e dei loro sviluppatori.
CREDITS_MODULES	8	Lista dei moduli e dei loro sviluppatori.
CREDITS_DOCS	16	La lista del gruppo di documentazione.
CREDITS_FULLPAGE	32	Solitamente utilizzato in combinazione con altri flag. Indica che la pagina completa HTML deve essere stampata includendo le infomazioni di altri flag.
CREDITS_QA	64	Elenca i riconoscimenti per il gruppo della qualità.
CREDITS_ALL	-1	Tutta la lista dei meriti, equivale a CREDITS_DOCS + CREDITS_GENERAL + CREDITS_GROUP + CREDITS_MODULES + CREDITS_FULLPAGE. Genera una pagina HTML completa. Questa è l'impostazione di default.

Tabella 3. Costanti di phpinfo()

Costante	Valore	Descrizione
INFO_GENERAL	1	La linea di configurazione, `php.ini` luogo, data di compila, Web Server, sistema e altro.
INFO_CREDITS	2	PHP Credits. Vedere anche phpcredits().
INFO_CONFIGURATION	4	Impostazioni correnti e di base delle opzioni PHP. Vedere anche ini_get().
INFO_MODULES	8	Moduli caricati e le loro impostazioni.
INFO_ENVIRONMENT	16	Variabili d'ambiente disponibili in `$_ENV`.
INFO_VARIABLES	32	Visualizza tutte le variabili predefinite da EGPCS (Environment, GET, POST, Cookie, Server).
INFO_LICENSE	64	Informazioni sulla licenza di PHP. Vedere anche faq sulla licenza.
INFO_ALL	-1	Visualizza tutto quanto descritto. Questo è il valore dei default.

ASSERT_ACTIVE (integer)
ASSERT_CALLBACK (integer)
ASSERT_BAIL (integer)
ASSERT_WARNING (integer)
ASSERT_QUIET_EVAL (integer)

Sommario
assert_options -- Imposta/ottiene vari parametri per assert
assert -- Verifica se un'asserzione è FALSE
dl -- Carica i moduli del PHP a runtime
extension_loaded -- Verifica se un modulo è già stato caricato
get_cfg_var -- Restituisce il valore di un'opzione di configurazione del PHP
get_current_user -- Restituisce il nome del proprietario dello script PHP
get_defined_constants -- Restituisve un array associativo con i nomi di tutte le costanti ed i loro valori
get_extension_funcs -- Restituisce una matrice con i nomi delle funzioni di un modulo
get_include_path -- Restituisce il valore del parametro di configurazione include_path
get_included_files -- Restituisce una matrice con i nomi dei file inclusi o richiesti
get_loaded_extensions -- Restituisce una matrice con il nome di tutti i moduli compilati e caricati
get_magic_quotes_gpc -- Restituisce l'attuale configurazione di magic quotes gpc
get_magic_quotes_runtime -- Restituisce l'impostazione corrente della direttiva magic_quotes_runtime
get_required_files -- Alias di get_included_files()
getenv -- Restituisce il valore di una variabile d'ambiente
getlastmod -- Restituisce la data dell'ultima modifica alla pagina
getmygid -- Restituisce il GID del proprietario dello script PHP
getmyinode -- Restituisce l'inode dello script
getmypid -- Restituisce l'ID del processo PHP
getmyuid -- Restituisce l'UID del proprietario dello script PHP
getopt -- Ottiene le opzioni dagli argomenti della linea di comando
getrusage -- Restituisce lo stato dell'utilizzo delle risorse
ini_alter -- Alias di ini_set()
ini_get_all -- Restituisce tutte le opzioni di configurazione
ini_get -- Restituisce il valore delle opzioni di configurazione
ini_restore -- Ripristina il valore di un'opzione di configurazione
ini_set -- Imposta le opzioni di configurazione
main -- Riferimento a main()
memory_get_usage -- Restituisce la quantità di memoria allocata dal PHP
php_ini_scanned_files -- Restituisce l'elenco dei file .ini leti dalla directory ini aggiuntiva
php_logo_guid -- Restituisce il guid del logo
php_sapi_name -- Restituisce il tipo di interfaccia tra il PHP ed il server web
php_uname -- Restituisce informazioni sul sistema operativo su cui gira il PHP
phpcredits -- Visualizza i credits per il PHP
phpinfo -- Visualizza diverse informazioni sul PHP
phpversion -- Restituisce la versione del PHP
putenv -- Imposta il valore di una variabile d'ambiente
restore_include_path -- Ripristina il valore dell'opzione include_path
set_include_path -- Imposta include_path
set_magic_quotes_runtime -- Imposta il valore attuale di magic_quotes_runtime
set_time_limit -- Limita il tempo massimo di esecuzione
version_compare -- Confronta due stringhe contenenti il numero di versione di "PHP-standardized"
zend_logo_guid -- Ottiene il guid del logo Zend
zend_version -- Restituisce il numero di versione dell'engine Zend

assert_options

(PHP 4, PHP 5)

assert_options -- Imposta/ottiene vari parametri per assert

Descrizione

mixed assert_options ( int what [, mixed value] )

Usando assert_options() si è in grado di impostare vari parametri di controllo per la funzione assert(), oppure ottenerne l'impostazione corrente.

Tabella 1. Opzioni di assert

opzione	parametro ini	default	descrizione
ASSERT_ACTIVE	assert.active	1	abilita l'assert()
ASSERT_WARNING	assert.warning	1	indica a PHP i generare un warning per ogni asserzione fallita
ASSERT_BAIL	assert.bail	0	termina l'esecuzione alla prima asserzione fallita
ASSERT_QUIET_EVAL	assert.quiet_eval	0	disabilita la gestione degli errori nelle espressioni di asserzione
ASSERT_CALLBACK	assert.callback	(`NULL`)	funzione utente da richiamare per le asserzioni fallite

assert_options() restituirà l'impostazione originale di ogni opzione, oppure FALSE se fallisce.

assert

(PHP 4, PHP 5)

assert -- Verifica se un'asserzione è FALSE

Descrizione

int assert ( mixed assertion )

assert() verifica se la data assertion è FALSE, nel caso intraprende le opportune azioni.

Se il parametro assertion è una stringa questo sarà considerato da assert() come codice PHP. I vantaggi di usare le stringhe con assertion sono che si ha meno overhead nella verifica e la visualizzazione dei messaggi che contengono assertion quando questa fallisce. Ciò significa che se si passa una condizione booleana come assertion, questa condizione non sarà mostrata come parametro della funzione che può essere definita con assert_options(), la condizione sarò in stringa prima di chiamare la funzione handler, e il valore booleano FALSE viene convertito in una stringa vuota.

Le asserzioni dovrebbero essere utilizzate solo per il debug. Si possono usare per controlli di coerenza che sono sempre TRUE e che, in caso contrario, indichino errori di programmazione, oppure per verificare la presenza o meni di certe caratteristiche, tipo le estensioni, oppure certi limiti di sistema o caratteristiche.

Le asserzioni non dovrebbero essere utilizzate per le normali operazioni di runtime quali il controllo dei parametri di input. Come regola si deve avere che il programma possa girare senza la presenza delle regole di asserzione.

Il comportamento di assert() può essere impostato tramite assert_options() oppure tramite .ini-settings come descritto nel pagine del manuale relative a quelle funzioni.

La funzione assert_options() e/o il parametro ASSERT_CALLBACK permetto di attivare una funzione di callback per gestire una asserzione fallita.

I callback di assert() sono particolarmente utili per costruire suite di test poiché permettono di catturare facilmente il codice passato all'assert, oltre alle informazioni su dove l'assert è scattato. Sebbene quest'ultime informazioni siano rilevabili anche con altri metodi, l'uso delle asserzione rende il tutto più semplice!

Le funzioni di callback devono accettare tre parametri. Il primo conterrà il nome del file in cui si trova l'asserzione fallita. Il secondo parametro conterrà il numero di linea dell'asserzione fallita, ed il terzo conterrà l'espressione dell'asserzione (se fornito - valori alfanumerici quali 1 o due" non saranno passati a questo parametro).

Esempio 1. Gestione di una asserzione fallita con codice personalizzato
<?php // Attiva le asserzioni assert_options(ASSERT_ACTIVE, 1); assert_options(ASSERT_WARNING, 0); assert_options(ASSERT_QUIET_EVAL, 1); // Crea la funzione personalizzata function my_assert_handler($file, $line, $code) { echo "<hr>Assertion Failed: File '$file'<br /> Line '$line'<br /> Code '$code'<br /><hr />"; } // Imposta il callback assert_options(ASSERT_CALLBACK, 'my_assert_handler'); // Crea una asserzione che fallisce assert('mysql_query("")'); ?>

dl

(PHP 3, PHP 4, PHP 5)

dl -- Carica i moduli del PHP a runtime

Descrizione

int dl ( string library )

La funzione carica il modulo di PHP passato nel parametro library. Il parametro library indica soltanto il nome del file del modulo da caricare il quale può dipendere dal piattaforma utilizzata. Ad esempio il modulo sockets (se compilato come modulo condiviso, non è il default!) sulle piattaforme Unix si chiama sockets.so, mentre in Windows si chiama php_sockets.dll.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento. Se la funzionalità di carico dei moduli non è disponibile (vedi note), oppure è stata disabilitata (sia disabilitando enable_dl oppure attivando modalità sicura nel php.ini), sarà generato un E_ERROR e sarà bloccata l'esecuzione dello script. Se dl() fallisce perché non riesce a caricare la libreria indicata, oltre a restituire FALSE verrà generato un messaggio di tipo E_WARNING.

Si può utilizzare extension_loaded() per testare se un modulo è veramente affidabile o meno. Questa funzione si applica sia a moduli built-in sia ai moduli caricati (tramite php.ini oppure dl()).

La funzione dl() è deprecata dal PHP 5. Piuttosto utilizzare Parametri per il carico dei moduli.

Esempio 1. Esempio di uso di dl()

<?php
// Caricare un modulo in base al sistema operativo
if (!extension_loaded('sqlite')) {
    if (strtoupper(substr(PHP_OS, 0, 3) == 'WIN')) {
        dl('php_sqlite.dll');
    } else {
        dl('sqlite.so');
    }
}

// Oppure la costante PHP_SHLIB_SUFFIX disponibile da 4.3.0
if (!extension_loaded('sqlite')) {
    $prefix = (PHP_SHLIB_SUFFIX == 'dll') ? 'php_' : '';
    dl($prefix . 'sqlite.' . PHP_SHLIB_SUFFIX);
}
?>

La directory da cui vengono caricate le estensioni dipende dal sistema operativo della macchina:

Windows - Se non viene impostato esplicitamente nel php.ini, i moduli sono caricati da c:\php4\extensions\ .

Unix - Se non viene impostato esplicitamente nel php.ini, la directory di default dipenda da

se il PHP è stato compilato con --enable-debug o meno
se il PHP è stato compilato con (versione sperimentale) ZTS (Zend Thread Safety) o meno
il valore attuale di ZEND_MODULE_API_NO (numero interno del modulo API Zend, il quale indica la data in cui si sono apportate le maggiori modifiche al modulo, ad esempio 20010901)

Quindi considerando quanto detto, la directory di default può essere <install-dir>/lib/php/extensions/ <debug-or-not>-<zts-or-not>-ZEND_MODULE_API_NO, /usr/local/php/lib/php/extensions/debug-non-zts-20010901 oppure /usr/local/php/lib/php/extensions/no-debug-zts-20010901.

Nota: La funzione dl() non è supportata dai web server multithread. Utilizzare il parametro del php.ini extensions quando si debba utilizzare tali server. Mentre le versioni CGI e CLI non hanno questa limitazione.

Nota: La dl() è sensibile alla maiuscole sulle piattaforme Unix.

Nota: Questa funzione è disabilitata nella modalitàsafe-mode

Vedere anche Direttive per il carimaneto dei moduli e extension_loaded().

extension_loaded

(PHP 3 >= 3.0.10, PHP 4, PHP 5)

extension_loaded -- Verifica se un modulo è già stato caricato

Descrizione

bool extension_loaded ( string name )

Restituisce TRUE se il modulo specificato da name è caricato, oppure FALSE.

Esempio 1. Esempio di uso di extension_loaded()
<?php if (!extension_loaded('gd')) { if (!dl('gd.so')) { exit; } } ?>

Si può verificare il nome dei vari moduli caricati tramite phpinfo(), o, se si sta utilizzando le versioni CGI o CLI di PHP, si può utilizzare l'opzione -m:
$ php -m [PHP Modules] xml tokenizer standard sockets session posix pcre overload mysql mbstring ctype [Zend Modules]

Nota: La funzione extension_loaded() utilizza i nomi interni dei moduli per verificare se tale modulo è disponibile o meno. La maggior parte dei nomi interni sono scritti in minuscolo, ma possono esserci moduli con nomi contenenti lettere maiuscole. Fare attenzione che questa funzione distingue tra lettere minuscole e maiuscole

Vedere anche get_loaded_extensions(), get_extension_funcs(), phpinfo() e dl().

get_cfg_var

(PHP 3, PHP 4, PHP 5)

get_cfg_var -- Restituisce il valore di un'opzione di configurazione del PHP

Descrizione

string get_cfg_var ( string varname )

Restituisce il valore corrente della variabile di configurazione indicata da varname, oppure FALSE se si verifica un errore.

La funzione non restituisce informazioni di configurazione nel caso in cui il PHP è compilato, o caricato da un file di configurazione di Apache (tramite le direttive php3_configuration_option).

Per verificare se il sistema utilizza un file di configurazione, tentare di ricavare il valore di cfg_file_path. Se è disponibile significa che si utilizza un file di configurazione.

Vedere anche ini_get().

get_current_user

(PHP 3, PHP 4, PHP 5)

get_current_user -- Restituisce il nome del proprietario dello script PHP

Descrizione

string get_current_user ( void )

Restituisce il nome del proprietario dello script PHP.

Vedere anche getmyuid(), getmygid(), getmypid(), getmyinode() e getlastmod().

get_defined_constants

(PHP 4 >= 4.1.0, PHP 5)

get_defined_constants -- Restituisve un array associativo con i nomi di tutte le costanti ed i loro valori

Descrizione

array get_defined_constants ( void )

Questa funzione restituisce i nomi ed i valori di tutte le costanti attualmente definite. Queste includono sia quelle create dalle estensioni sia quelle create con la funzione define().

Ad esempio la linea seguente:

<?php
print_r(get_defined_constants());
?>

visualizzerà il seguente elenco:

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
)

Vedere anche: defined(), get_loaded_extensions(), get_defined_functions() e get_defined_vars().

get_extension_funcs

(PHP 4, PHP 5)

get_extension_funcs -- Restituisce una matrice con i nomi delle funzioni di un modulo

Descrizione

array get_extension_funcs ( string module_name )

Questa funzione restituisce i nomi di tutte le funzioni definite all'interno del modulo indicato da module_name.

Nota: Il parametro module_name deve essere in minuscolo.

Ad esempio, il seguente comando:

<?php
print_r(get_extension_funcs("xml"));
print_r(get_extension_funcs("gd"));
?>

visualizzerà l'elenco delle funzioni definite nei moduli xml e gd.

Vedere anche: get_loaded_extensions()

get_include_path

(PHP 4 >= 4.3.0, PHP 5)

get_include_path -- Restituisce il valore del parametro di configurazione include_path

Descrizione

string get_include_path ( void )

Restituisce il valore di include_path.

Esempio 1. Esempio di uso di get_include_path()
<?php // Funziona da PHP 4.3.0 echo get_include_path(); // Funziona in tutte le versioni di PHP echo ini_get('include_path'); ?>

Vedere anche ini_get(), restore_include_path(), set_include_path() e include().

get_included_files

(PHP 4, PHP 5)

get_included_files -- Restituisce una matrice con i nomi dei file inclusi o richiesti

Descrizione

array get_included_files ( void )

Restituisce una matrice contenente i nomi di tutti i file che sono stati includi tramite le funzioni include(), include_once(), require() oppure require_once().

Lo script originario viene considerato come 'file incluso', pertanto sarà elencato insieme agli altri file referenziati da include() e simili.

File che sono inclusi più volte saranno elencati soltanto una volta sola

Nota: File inclusi tramite la direttiva auto_prepend_file non saranno inseriti nella matrice.

Esempio 1. Esempio di uso di get_included_files() del file (abc.php)
<?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"; } ?>
l'esempio visualizzerà:
abc.php test1.php test2.php test3.php test4.php

Nota: In PHP 4.0.1pl2 e nelle versioni precedenti get_included_files() assumeva che i file inclusi avessero come estensione .php; file con altre estensioni erano ignorati. La matrice restituita da get_included_files() era una matrice associativa e riportava soltanto i file inclusi con include() e include_once().

Vedere anche include(), include_once(), require(), require_once() e get_required_files().

get_loaded_extensions

(PHP 4, PHP 5)

get_loaded_extensions -- Restituisce una matrice con il nome di tutti i moduli compilati e caricati

Descrizione

array get_loaded_extensions ( void )

Restituisce una matrice con il nome di tutti i moduli compilati e caricati nell'interprete PHP.

Ad esempio la seguente linea:

<?php
print_r(get_loaded_extensions());
?>

restituirà qualcosa simile a:

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
)

Vedere anche get_extension_funcs(), extension_loaded(), dl() e phpinfo().

get_magic_quotes_gpc

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

get_magic_quotes_gpc -- Restituisce l'attuale configurazione di magic quotes gpc

Descrizione

int get_magic_quotes_gpc ( void )

Restituisce l'impostazione attuale della direttiva di configurazione magic_quotes_gpc (0 uguale a off, 1 per on).

Nota: Se la direttiva magic_quotes_sybase è impostata a ON, questa è prioritaria rispetto a magic_quotes_gpc. Pertanto, anche se get_magic_quotes() restituisce TRUE ne i doppi apici, ne i backslashes o i NUL saranno preceduti dal caratteri di escape. Lo saranno soltanto gli apici singoli. In questo caso saranno: ''

Si ricordi che magic_quotes_gpc non può essere impostata a runtime.

Esempio 1. Esempio di uso di get_magic_quotes_gpc()
<?php echo get_magic_quotes_gpc(); // 1 echo $_POST['lastname']; // O\'reilly echo addslashes($_POST['lastname']); // O\\\'reilly if (!get_magic_quotes_gpc()) { $lastname = addslashes($_POST['lastname']); } else { $lastname = $_POST['lastname']; } echo $lastname; // O\'reilly $sql = "INSERT INTO lastnames (lastname) VALUES ('$lastname')"; ?>

Nell'ottica di scrittura di codice portabile (codice che funzioni in qualsiasi ambiente), o, se non si hanno i permessi di modifica del php.ini, è possibile disabilitare gli effetti della funzione da script. Questo può essere fatto in due modi, o con una impostazione da .htaccess (php_value magic_quotes_gpc 0), oppure aggiungendo il codice sottostante allo script.
Esempio 2. Disattivare magic quotes da script
<?php if (get_magic_quotes_gpc()) { function stripslashes_deep($value) { $value = is_array($value) ? array_map('stripslashes_deep', $value) : stripslashes($value); return $value; } $_POST = array_map('stripslashes_deep', $_POST); $_GET = array_map('stripslashes_deep', $_GET); $_COOKIE = array_map('stripslashes_deep', $_COOKIE); } ?>
Il parametro magic-quote è stato aggiunto per ridurre il rischio di scrivere codice pericoloso da parte dei principianti. Se si disabilita magic-quote, occorre prestare molta attenzione a proteggersi dagli attacchi di SQL injection.

Vedere anche addslashes(), stripslashes(), get_magic_quotes_runtime() e ini_get().

get_magic_quotes_runtime

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

get_magic_quotes_runtime -- Restituisce l'impostazione corrente della direttiva magic_quotes_runtime

Descrizione

int get_magic_quotes_runtime ( void )

Restituisce l'impostazione corrente della direttiva magic_quotes_runtime (0 per off, 1 per on).

Vedere anche get_magic_quotes_gpc() e set_magic_quotes_runtime().

get_required_files

(PHP 4, PHP 5)

get_required_files -- Alias di get_included_files()

Descrizione

Questa funzione è un alias di get_included_files().

getenv

(PHP 3, PHP 4, PHP 5)

getenv -- Restituisce il valore di una variabile d'ambiente

Descrizione

string getenv ( string varname )

Restituisce il valore della variabile d'ambiente varname, oppure FALSE in caso di errore.

<?php
$ip = getenv("REMOTE_ADDR"); // get the ip number of the user
?>

Si può accedere all'elenco di tutte le variabili d'ambiente utilizzando phpinfo(). Si può avere una descrizione della maggior parte di queste alla pagina specifiche CGI , in modo particolare nella pagina delle variabili d'ambiente.

Nota: Questa funzione non gira in modalità ISAPI.

Vedere anche putenv().

getlastmod

(PHP 3, PHP 4, PHP 5)

getlastmod -- Restituisce la data dell'ultima modifica alla pagina

Descrizione

int getlastmod ( void )

Restituisce la data dell'ultima modifica alla pagina corrente. Il valore restituito è un timestamp, può essere elaborato con la funzione date(). Restituisce FALSE su errore.

Esempio 1. Esempio di uso di getlastmod()
<?php // outputs e.g. 'Last modified: March 04 1998 20:43:59.' echo "Last modified: " . date ("F d Y H:i:s.", getlastmod()); ?>

Nota: Se si è interessati ad avere la data dell'ultima modifica di un'altro file, si consideri l'uso di filemtime().

Vedere anche date(), getmyuid(), getmygid(), get_current_user(), getmyinode(), getmypid() e filemtime().

getmygid

(PHP 4 >= 4.1.0, PHP 5)

getmygid -- Restituisce il GID del proprietario dello script PHP

Descrizione

int getmygid ( void )

Restituisce l'ID del gruppo del proprietario dello script, oppure FALSE per errore.

Vedere anche getmyuid(), getmypid(), get_current_user(), getmyinode() e getlastmod().

getmyinode

(PHP 3, PHP 4, PHP 5)

getmyinode -- Restituisce l'inode dello script

Descrizione

int getmyinode ( void )

Restituisce l'inode dello script, oppure FALSE su errore.

Vedere anche getmygid(), getmyuid(), get_current_user(), getmypid() e getlastmod().

Nota: Questa funzione non è implementata su piattaforme Windows

getmypid

(PHP 3, PHP 4, PHP 5)

getmypid -- Restituisce l'ID del processo PHP

Descrizione

int getmypid ( void )

Restituisce l'ID del processo PHP, oppure FALSE in caso errore.

Avvertimento

Gli ID di processo non sono univoci, poichè sono sorgenti di bassa entropia. Si raccomanda di non basarsi sul pid nei contesti basati sulla sicurezza.

Vedere anche getmygid(), getmyuid(), get_current_user(), getmyinode() e getlastmod().

getmyuid

(PHP 3, PHP 4, PHP 5)

getmyuid -- Restituisce l'UID del proprietario dello script PHP

Descrizione

int getmyuid ( void )

Restituisce l'ID utente del proprietario dello script, oppure FALSE in caso di errore.

Vedere anche getmygid(), getmypid(), get_current_user(), getmyinode() e getlastmod().

getopt

(PHP 4 >= 4.3.0, PHP 5)

getopt -- Ottiene le opzioni dagli argomenti della linea di comando

Descrizione

array getopt ( string options [, array longopts] )

Restituisce una matrcie associativa con l'accoppiata opzione / valore basata sulle opzioni attese indicate in options, oppure FALSE in caso di errore.

Sulle piattaforme che supportano la funzione C getopt_long, le opzioni 'lunghe' possono essere spcificate con il parametro longopts (dal PHP 4.3.0).

<?php
// parse the command line ($GLOBALS['argv'])
$options = getopt("f:hp:");
?>

Il parametro options può contenere i seguenti elementi: caratteri individualie e caratteri seguiti dai due punti per indicare un'opzione seguita da un valore. Ad esempio, la stringa di opzione x identifica il parametro -x, e una stringa x: identifica un parametro ed il suo valore -x argument. Non è rilevante se il vlore è precedeuto da spazio.

Questa funzione restituisce l'accoppiata opzione / valore. Se l'opzione non ha valori, il valore restituito sarà FALSE.

Nota: Questa funzione non è implementata su piattaforme Windows

getrusage

(PHP 3 >= 3.0.7, PHP 4, PHP 5)

getrusage -- Restituisce lo stato dell'utilizzo delle risorse

Descrizione

array getrusage ( [int who] )

Questa funzione è un interfaccia a getrusage(2). Restituisce una matrice associativa contente le informazioni restituite dalla chiamata di sistema. Se il parametro who vale 1, getrusage()sarà eseguita con RUSAGE_CHILDREN.

Tutte le informazioni sono accessibili tramite i nomi dei campi documentati.

Esempio 1. Esempio di uso di getrusage()
<?php $dat = getrusage(); echo $dat["ru_nswap"]; // numero di swap echo $dat["ru_majflt"]; // numero di page faults echo $dat["ru_utime.tv_sec"]; // tempo utente utilizzato (seconds) echo $dat["ru_utime.tv_usec"]; // tempo utente utilizzato (microseconds) ?>
Per maggior dettagli si veda la pagina di getrusage(2) nel manuale del proprio sistema.

Nota: Questa funzione non è implementata su piattaforme Windows

ini_alter

(PHP 4, PHP 5)

ini_alter -- Alias di ini_set()

Descrizione

Questa funzione è un alias di ini_set().

ini_get_all

(PHP 4 >= 4.2.0, PHP 5)

ini_get_all -- Restituisce tutte le opzioni di configurazione

Descrizione

array ini_get_all ( [string extension] )

Restituisce tutte le opzioni di configurazione come una matrice associativa. Se viene specificato il parametro opzionale extension La funzione restituirà solo le opzioni specifiche per quel modulo.

I nomi delle opzioni faranno da indice per la matrcie restituita, quindi gli elementi potranno essere: global_value (impostata in php.ini), local_value (impostata in ini_set() oppure in .htaccess), e access (il livello di accesso). Per avere informazioni su cosa siano i livello di accesso, vedere la pagina del manuale su modifiche di configurazione

Nota: Per le direttive è possibile avere più livelli di accesso, è per questo che access restituisce le appropriate maschere di bit.

Esempio 1. Esempio di uso di ini_get_all()
<?php $inis = ini_get_all(); print_r($inis); ?>
Parte dell'aoutput potrebbe essere:
Array ( [allow_call_time_pass_reference] => Array ( [global_value] => 1 [local_value] => 1 [access] => 6 ) [allow_url_fopen] => Array ( [global_value] => 1 [local_value] => 1 [access] => 7 ) ... )

Vedere anche ini_get(), ini_restore(), ini_set(), get_loaded_extensions() e phpinfo().

ini_get

(PHP 4, PHP 5)

ini_get -- Restituisce il valore delle opzioni di configurazione

Descrizione

string ini_get ( string varname )

Restituisce il valore delle opzioni di configurazione. In caso di errore, tipo la richiesta per un valore inesistente, sarà restituita una stringa vuota.

Richieste per valori booleani: Nel file ini, il valore booleano off sarà restituito come stringa vuota o "0", mentre il valore on sarà restituito come "1".

Richieste per le dimensioni della memoria: Diversi parametri attinenti alle dimensioni di memoria, tipo upload_max_filesize sono registrati nel php.ini in notazione abbreviata. La funzione ini_get() restituirà l'esatto valore presente nel php.ini, e NON l'intero equivalente. L'esecuzione delle normali funzioni aritmetiche su questi valori potrà dare risultati inattesi. L'esempio seguente illustra come si possa convertire la notazione breve in byte in modo molto simile a come fa il PHP.

Esempio 1. Qualche esempio di ini_get()
<?php /* Il nostro php.ini contiene i seguenti parametri: 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 = $val{strlen($val)-1}; switch($last) { case 'k': case 'K': return (int) $val * 1024; break; case 'm': case 'M': return (int) $val * 1048576; break; default: return $val; } } ?>
Lo script produrrà:
display_errors = 1 register_globals = 0 post_max_size = 8M post_max_size+1 = 9 post_max_size in bytes = 8388608

Vedere anche: get_cfg_var(), ini_get_all(), ini_restore() e ini_set().

ini_restore

(PHP 4, PHP 5)

ini_restore -- Ripristina il valore di un'opzione di configurazione

Descrizione

void ini_restore ( string varname )

Ripristina il valore della data opzione di configurazione allo stato originale.

Vedere anche ini_get(), ini_get_all() e ini_set().

ini_set

(PHP 4, PHP 5)

ini_set -- Imposta le opzioni di configurazione

Descrizione

php_ini_scanned_files() restituisce un elenco separato da virgola dei file di configurazione letti dopo il php.ini. Questi file sono cercati nella directory specificata dall'opzione --with-config-file-scan-dir impostata al momento della compila.

La funzione restituisce la lista separata da virgola se riesce. Al contrario, se l'impostazione --with-config-files-scan-dir non è configurata la funzione resttuisce FALSE. Se un file non è riconoscibile, questo sarà inserito nell'elenco restituito, ma il PHP darà errore. Questo errore sarà visualizzato sia al momento della compila sia utilizzando php_ini_scanned_files().

La lista restituita comprende anche il percorso di include specificato in --with-config-file-scan-dir. Ogni virgola è seguita da un carattere di a capo (newline).

Esempio 1. Un semplice esempio di lista restuita dalla funzione
<?php if ($filelist = php_ini_scanned_files()) { if (strlen($filelist) > 0) { $files = explode(',', $filelist); foreach ($files as $file) { echo "<li>" . trim($file) . "</li>\n"; } } } ?>

Vedere anche ini_set() e phpinfo().

php_logo_guid

(PHP 4, PHP 5)

php_logo_guid -- Restituisce il guid del logo

Descrizione

string php_logo_guid ( void )

Questa funzione restituisce l'ID che può essere utlizzato per visualizzar il logo PHP pre-inserito.

Esempio 1. Esempio di uso di php_logo_guid()
<?php echo '<img src="' . $_SERVER['PHP_SELF'] . '?=' . php_logo_guid() . '" alt="PHP Logo !" />'; ?>

Vedere anche phpinfo(), phpversion(), phpcredits() e zend_logo_guid().

php_sapi_name

(PHP 4 >= 4.0.1, PHP 5)

php_sapi_name -- Restituisce il tipo di interfaccia tra il PHP ed il server web

Descrizione

string php_sapi_name ( void )

php_sapi_name() restituisce un testo minuscolo che descrive il tipo di interfaccia tra il PHP ed il server web (Server API, SAPI). In caso di CGI PHP, la stringa è "cgi", nel caso si usi mod_php per Apache, il testo sarà "apache" e così via.

Esempio 1. Esempio di uso di php_sapi_name()
<?php $sapi_type = php_sapi_name(); iif (substr($sapi_type, 0, 3) == 'cgi') { echo "Si usa CGI PHP\n"; } else { echo "Non si usa CGI PHP\n"; } ?>

php_uname

(PHP 4 >= 4.0.2, PHP 5)

php_uname -- Restituisce informazioni sul sistema operativo su cui gira il PHP

Descrizione

string php_uname ( [string mode] )

php_uname() restituisce una stringa con la descrizione del sistema operativo su cui gira PHP. Se si desidera semplicemente il nome del sistema operativo, si utilizzi la costante PHP_OS, ma si ricordi che questa costante contiene il nome del sistema operativo su cui il PHP è stato compilato.

Sui sistemi Unix, la funzione passa a visualizzare il sistema operativo su cui il PHP è stato compilato, se non è in grado di determinare le imformazioni del sistema operativo su cui il PHP gira.

mode definisce quali informazioni debbano essere restituite:

'a': Questo è il default. Contiene tutte le modalità nella sequenza "s n r v m".
's': Nome del sistema operativo. Es. FreeBSD.
'n': Nome del server. Es. localhost.example.com.
'r': Nome del rilascio. Es. 5.1.2-RELEASE.
'v': Informazioni sulla versione. Varia molto in base al sistema operativo.
'm': Tipo di macchina. Es. i386.

Esempio 1. Alcuni esempi di php_uname()
<?php echo php_uname(); echo PHP_OS; /* possibili output: 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!'; } ?>

Esistono alcune Costanti PHP predefinite che possono essere di aiuto, ad esempio:

Esempio 2. Alcune costanti relative al OS
<?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; // ; ?>

Vedere anche phpversion(), php_sapi_name() e phpinfo().

phpcredits

(PHP 4, PHP 5)

phpcredits -- Visualizza i credits per il PHP

Descrizione

void phpcredits ( [int flag] )

Questa funzione visualizza la lista dei riconoscimenti per gli sviluppatori del PHP, dei vari moduli, eccetera. Genera il codice HTML appropriato per inserire l'informazine in una pagina. IL parametro opzionale flag, per default vale CREDITS_ALL, permette di selezionare di personalizzare la lista. Ad esempio per stampare l'elenco generale, utilizzare:

<?php
phpcredits(CREDITS_GENERAL);
?>

Se si vuole stampare l'elenco degli sviluppatori principali e del grupo di documentazione, in una pagina proprio conto, utilizzare:

<?php
phpcredits(CREDITS_GROUP + CREDITS_DOCS + CREDITS_FULLPAGE);
?>

E se si desidera inserire l'elenco completo nella propria pagina, utilizzare un codice simile al seguente:

<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>

Tabella 1. Flag pre-definiti phpcredits()

nome	descrizione
CREDITS_ALL	Tutta la lista dei meriti, equivale a CREDITS_DOCS + CREDITS_GENERAL + CREDITS_GROUP + CREDITS_MODULES + CREDITS_FULLPAGE. Genera una pagina HTML completa.
CREDITS_DOCS	La lista del gruppo di documentazione
CREDITS_FULLPAGE	Solitamente utilizzato in combinazione con altri flag. Indica che la pagina completa HTML deve essere stampata includendo le infomazioni di altri flag.
CREDITS_GENERAL	Lista generale: design e progetto del linguaggio, autori del PHP 4.0 e del modulo SAPI.
CREDITS_GROUP	Lista degli sviluppatori principali
CREDITS_MODULES	Lista dei moduli e dei loro sviluppatori
CREDITS_SAPI	Lista delle API server e dei loro sviluppatori

Vedere anche phpinfo(), phpversion() e php_logo_guid().

phpinfo

(PHP 3, PHP 4, PHP 5)

phpinfo -- Visualizza diverse informazioni sul PHP

Descrizione

int phpinfo ( [int what] )

Visualizza molte informazioni sullo stato corrente del PHP Queste includono informazioni sulle opzioni di compila del PHP, sui moduli, la versioen di PHP, informazioni sul server e sull'ambiente (se compilato come modulo), l'ambiente PHP, la versione di OS, percorsi, valori delle configurazioni base e attauli, intestazioni HTTP e la licenza del PHP.

Dato che ogni sistema ha una cofigurazione differente, phpinfo() viene comunemente utilizzato per verificare le impostazioni di configurazione e le variabili predefinite disponibili in un dato sistema. Inoltre, phpinfo() è utili come strumento di debug poichè visualizza tutti i dati EGPCS (Environment, GET, POST, Cookie, Server).

L'output può essere personalizzato passando una o più delle seguenti costanti sommate a livello di bit nel parametro opzionale what. Le costanti, o i rispettivi valori, possono essere combinati anche con l'operatore or.

Tabella 1. Opzioni di phpinfo()

Nome (constant)	Valore	Descrizione
INFO_GENERAL	1	La linea di configurazione, `php.ini` luogo, data di compila, Web Server, sistema e altro.
INFO_CREDITS	2	PHP 4 Credits. Vedere anche phpcredits().
INFO_CONFIGURATION	4	Impostazioni correnti e di base delle opzioni PHP. Vedere anche ini_get().
INFO_MODULES	8	Moduli caricati e le loro impostazioni. Vedere anche get_loaded_extensions().
INFO_ENVIRONMENT	16	Variabili d'ambiente disponibili in `$_ENV`.
INFO_VARIABLES	32	Visualizza tutte le variabili predefinite da EGPCS (Environment, GET, POST, Cookie, Server).
INFO_LICENSE	64	Informazioni sulla licenza di PHP. Vedere anche faq sulla licenza.
INFO_ALL	-1	Visualizza tutto quanto descritto. Questo è il valore dei default.

Esempio 1. Esempio di uso di phpinfo()
<?php // Visualizza tutte le informazioni, default: INFO_ALL phpinfo(); // Solo le informazioni sui moduli // phpinfo(8) visualizza il medesimo risultato phpinfo(INFO_MODULES); ?>

Nota: La visualizzazione di parte delle informazioni è disabilitata quando expose_php viene impostato a off. Queste includono i loghi PHP e Zend, e i credits.

Nota: La funzione phpinfo() produce un testo normale anzichè un file HTML quando è utilizzata in modalità CLI.

Vedere anche phpversion(), phpcredits(), php_logo_guid(), ini_get(), ini_set(), get_loaded_extensions() e la sezione sulle Variabili Predefinite.

phpversion

(PHP 3, PHP 4, PHP 5)

phpversion -- Restituisce la versione del PHP

Descrizione

string phpversion ( void )

Restituisce una stringa contenente la versione dell'interprete PHP.

Nota: Questa informazione è anche disponibile come costante predefinita PHP_VERSION.

Esempio 1. Esempio di uso di phpversion()
<?php // Ad esempio visualizza 'Current PHP version: 4.1.1' echo 'Current PHP version: ' . phpversion(); ?>

Vedere anche version_compare(), phpinfo(), phpcredits(), php_logo_guid() e zend_version().

putenv

(PHP 3, PHP 4, PHP 5)

putenv -- Imposta il valore di una variabile d'ambiente

Descrizione

void putenv ( string setting )

Imposta una variable nell'ambiente del server. La variabile d'ambiente esisterà solo per lòa durata dsello script Alla fine di questo l'ambiente sarà ripristinato allo stato originario.

L'impostazione di certe variabili d'ambiente può causare dei problemi di sicurezza. La direttiva safe_mode_allowed_env_vars contiene un'elenco separato da virgole di prefissi. In Mpodlità Sicura, l'utente può soltanto alterare le variabili d'ambiente il cui nome inizia con il prefisso indicato da questa direttiva. Per default, gli utenti sono abilitati ad impostare le variabili d'ambiente con inizino con PHP_ (ad esempio PHP_FOO=BAR). Nota: Se questa direttiva è vuota, il PHP permetterà all'utente di modificare QUALSIASI variabile d'ambiente!

La direttiva safe_mode_protected_env_vars contiene un elenco separato da virgola di variabili d'ambiente, che l'utente non può modificare tramite putenv(). Questa variabili saranno protette anche se safe_mode_allowed_env_vars autorizza la modifica a queste.

bool set_magic_quotes_runtime ( int new_setting )

Imposta il valore del parametro di configurazione magic_quotes_runtime (0 per off, 1 per on).

Vedere anche get_magic_quotes_gpc() e get_magic_quotes_runtime().

set_time_limit

(PHP 3, PHP 4, PHP 5)

set_time_limit -- Limita il tempo massimo di esecuzione

Descrizione

void set_time_limit ( int seconds )

Imposta il limite massimo in secondi di durata dello script. Se si raggiunge questo limite, lo script viene interrotto con un errore fatale. Per default questo limite è impostato a 30 secondi o, se esiste, al valore di max_execution_time nel php.ini. Se il parametro seconds viene impostato a zero, non si impone alcun limite di tempo.

Quando viene eseguita la funzione set_time_limit(), questa re-imposta il il contatore del tempo di esecuzione a zero. In altre parole, se il timeout è impostato al default di 30 secondi, e dopo 25 secondi di esecuzione si richiama la funzione con set_time_limit(20), lo script potrà girare per 45 secondi.

Avvertimento

La funzione set_time_limit() non ha effetto quando il PHP gira in modalità sicura. Non esistono soluzioni alternative se non quella di disabilitare la modalità sicura o modificare il limite nel php.ini.

Nota: La funzione set_time_limit() e la configurazione max_execution_time agiscono solo sull'esecuzione dello script in cui sono. Qualsiasi tempo perso in attività esterno allo script, tipo le chiamate di sistema tramite system(), operazioni sugli stream, query di database, ecc non sono incluse nel conteggio del tempo massimo che ha lo script per girare.

Vedere anche max_execution_time e la direttiva max_input_time.

version_compare

(PHP 4 >= 4.1.0, PHP 5)

version_compare -- Confronta due stringhe contenenti il numero di versione di "PHP-standardized"

Descrizione

int version_compare ( string version1, string version2 [, string operator] )

version_compare() confronta due numeri di versione "PHP-standardized" . Questa funzione è utile quando si desideri che funzioni solo con alcune versioni di PHP.

La funzione version_compare() restituisce -1 se la prima verisone è minore della seconda, 0 se sono uguali, +1 se la sceonda è inferiore.

Per prima cosa la funzione sostituisce nella strina di versione le lettere _, - e + con un puntot . ed inserisce un punto . prima e dopo ogni carattere non numerico, in modo che, ad esempio, '4.3.2RC1' diventi ''4.3.2.RC.1'. Quindi divite il testo come se usasse explode('.', $ver). Poi confronta le parti cominciando da sinistra verso destra Se una parte contiene versioni speciali queste sono gestite nel seguente modo: dev < alpha = a < beta = b < RC < pl. In quest modo possono essere confrontati non solo differenti livelli di versioni quali '4.1' e '4.1.2', ma anche versioni di PHP in fase di sviluppo.

Specificando il terzo parametro opzionale operator si possono testare particolari relazioni. I possibili operatori sono: <, lt, <=, le, >, gt, >=, ge, ==, =, eq, !=, <>, ne. Utilizzando questi parametri, la funzione restituirà 1 se la relazione è una di quelle specificate dall'operatore, altrimenti 0.

Esempio 1. Esempio di uso di version_compare()
<?php // prints -1 echo version_compare("4.0.4", "4.0.6"); // queste stampano 1 echo version_compare("4.0.4", "4.0.6", "<"); echo version_compare("4.0.6", "4.0.6", "eq"); ?>

zend_logo_guid

(PHP 4, PHP 5)

zend_logo_guid -- Ottiene il guid del logo Zend

Description

string zend_logo_guid ( void )

Questa funzioen restituisce l'ID che può essere utilizzato per visualizzare il logo Zend usando l'immagine inserita nel PHP.

Esempio 1. Esempio di uso di zend_logo_uid()
<?php echo '<img src="' . $_SERVER['PHP_SELF'] . '?=' . zend_logo_guid() . '" alt="Zend Logo !" />'; ?>

Vedere anche php_logo_guid().

zend_version

(PHP 4, PHP 5)

zend_version -- Restituisce il numero di versione dell'engine Zend

Descrizione

string zend_version ( void )

Restituisce una stringa contenente il numero di versione dell'engine Zend.

Esempio 1. Esempio di uso di zend_version()
<?php // ad esempio visualizza: 'Zend engine version: 1.0.4' echo "Zend engine version: " . zend_version(); ?>

Vedere anche phpinfo(), phpcredits(), php_logo_guid() e phpversion().

CXII. Funzioni POSIX

Introduzione

Questo modulo contiene un'interfaccia alle funzioni definite dallo standard IEEE 1003.1 (POSIX.1) che non sono accessibili in altro modo. Ad esempio lo standard POSIX.1 definisce le funzioni open(), read(), write() e close() che tradizionalmente sono parte di PHP 3 da lungo tempo. Altre funzioni più specifiche del sistema operativo non sono disponibili, e quindi con questo modulo si cerca di porre rimedio a questa mancanza dando un facile accesso a queste funzioni.

Avvertimento

Con le funzioni POSIX si possono ricavare informazioni sensibili tipo posix_getpwnam() e simili. Nessuna delle funzioni POSIX esegue alcun tipo di controllo di accesso quando è abilitata la modalità sicura. Pertanto è vivamente consigliato di disabilitare l'estensione POSIX (impostare --disable-posix nella linea di configurazione) se si opera con la modalità sicura.

Nota: Questo modulo non è disponibile su piattaforme Windows.

Installazione

Le funzioni POSIX sono abilitate per default. Si possono disabilitare con --disable-posix.

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

POSIX_F_OK (integer): Check whether the file exists.
POSIX_R_OK (integer): Check whether the file exists and has read permissions.
POSIX_W_OK (integer): Check whether the file exists and has write permissions.
POSIX_X_OK (integer): Check whether the file exists and has execute permissions.
POSIX_S_IFBLK (integer): Block special file
POSIX_S_IFCHR (integer): Character special file
POSIX_S_IFIFO (integer): FIFO (named pipe) special file
POSIX_S_IFREG (integer): Normal file
POSIX_S_IFSOCK (integer): Socket

Nota: These constants are available since PHP 5.1.0. Please also note that some of them may not be available in your system.

Vedere anche:

Potrebbe essere interessante anche la sezione Funzioni per il controllo dei processi.

Sommario
posix_access -- Determine accessibility of a file
posix_ctermid -- Restituisce il percorso del terminale
posix_get_last_error -- Recupera il numero di errore dell'ultima funzione posix non riuscita
posix_getcwd -- Percorso della directory corrente
posix_getegid -- Restituisce l'ID del gruppo per il processo corrente
posix_geteuid -- Restituisce l'ID dell'utente per il processo corrente
posix_getgid -- Restituisce il reale ID del gruppo per il processo corrente
posix_getgrgid -- Restituisce informazioni su un gruppo dato il suo ID
posix_getgrnam -- Restituisce le informazioni di un gruppo dato il nome
posix_getgroups -- Restituisce i gruppi per il processo corrente
posix_getlogin -- Restituisce il nome dell'utente
posix_getpgid -- Restituisce l'id del gruppo del processo per il controllo dei job
posix_getpgrp -- Restituisce l'identificatore di gruppo per il processo corrente
posix_getpid -- Restituisce l'ID per il processo corrente
posix_getppid -- Restituisce l'ID del processo genitore
posix_getpwnam -- Restituisce informazioni su un utente dato il nome
posix_getpwuid -- Restituisce le informazioni di un utente dato il suo ID
posix_getrlimit -- Restituisce informazioni sui limiti delle risorse del sistema
posix_getsid -- Restituisce il sid corrente per un processo
posix_getuid -- Restituisce il reale ID dell'utente per il processo corrente
posix_isatty -- Determina se il decrittore di file è un terminale
posix_kill -- Invia un segnale ad un processo
posix_mkfifo -- Crea un file speciale di tipo fifo (una pipe nominata)
posix_mknod -- Create a special or ordinary file (POSIX.1)
posix_setegid -- Imposta l'effettivo GID per il processo corrente
posix_seteuid -- Imposta l'effettivo UID del processo corrente
posix_setgid -- Imposta il GID per il processo corrente
posix_setpgid -- Imposta l'id di gruppo per il controllo dei job
posix_setsid -- Rende il processo corrente leader di sessione
posix_setuid -- Imposta l'UID per il processo corrente
posix_strerror -- Recupera il messaggio di errore di un dato codice di errore
posix_times -- Restituisce il tempo del processo
posix_ttyname -- Determina il nome del device per il terminale
posix_uname -- Restituisce il nome del sistema

posix_access

(PHP 5 >= 5.1.0RC1)

posix_access -- Determine accessibility of a file

Descrizione

bool posix_access ( string file [, int mode] )

posix_access() checks the user's permission of a file.

Nota: Quando safe-mode è abilitato, PHP controlla che i file o le directory sulle quali si sta andando a lavorare, abbiano lo stesso UID dello script che è in esecuzione.

Elenco dei parametri

file

The name of the file to be tested.

mode

A mask consisting of one or more of POSIX_F_OK, POSIX_R_OK, POSIX_W_OK and POSIX_X_OK. Defaults to POSIX_F_OK.

POSIX_R_OK, POSIX_W_OK and POSIX_X_OK request checking whether the file exists and has read, write and execute permissions, respectively. POSIX_F_OK just requests checking for the existence of the file.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 1. posix_access() example
This example will check if the $file is readable and writable, otherwise will print an error message.
<?php $file = 'some_file'; if (posix_access($file, POSIX_R_OK | POSIX_W_OK)) { echo 'The file is readable and writable!'; } else { $error = posix_get_last_error(); echo "Error $error: " . posix_strerror($error); } ?>

array posix_getgrgid ( int gid )

Restituisce un array con le informazioni del gruppo, oppure FALSE se si verifica un errore. Se gid non è un numero la funzione restituisce NULL e genera un errore di tipo E_WARNING.

Esempio 1. Esempio dell'utilizzo di posix_getgrgid()
<?php $groupid = posix_getegid(); $groupinfo = posix_getgrgid($groupid); print_r($groupinfo); ?>
Output dell'esempio:
Array ( [name] => toons [passwd] => x [members] => Array ( [0] => tom [1] => jerry ) [gid] => 42 )

Nota: A partire da PHP 4.2.0, la funzione restituisce l'elenco dei membri del gruppo in un array ordinato per nome. Precedentemente si restituiva un intero (il numero dei membri del gruppo) ed i nomi dei membri doveva essere recuperato tramite l'indice numerico.

Vedere anche posix_getegid(), filegroup(), stat() e safe_mode_gid.

posix_getgrnam

(PHP 3 >= 3.0.13, PHP 4, PHP 5)

posix_getgrnam -- Restituisce le informazioni di un gruppo dato il nome

Descrizione

array posix_getgrnam ( string name )

int posix_getpgid ( int pid )

array posix_getpwnam ( string username )

La funzione restituisce un array associativo contenente le informazioni sull'utente con nome specificato nel parametro username.

Gli elementi dell'array sono:

Tabella 1. Array delle informazioni utente

Elemento	Descrizione
name	L'elemento name solitamente contiene il nome dell'utente. Questo è un nome corto, di solito meno di 16 caratteri, non il nome reale, completo, dell'utente. Questo dovrebbe essere uguale al parametro `username` passato alla funzione e quindi ridondante.
passwd	L'elemento passwd contiene la password dell'utente in formato criptato. Spesso, ad esempio nei sistemi utilizzano password "shadow", vengono restituiti degli asterischi.
uid	ID dell'utente in formato numerico.
gid	ID del gruppo a cui appartiene l'utente. Utilizzare la funzione posix_getgrgid() per ottenere il nome del gruppo e l'elenco dei suoi membri.
gecos	GECOS è un termine obsoleto che si riferisce a campi del comando finger su sistemi Honeywell. Tuttavia il campo è sopravvissuto ed il suo contenuto è stato formalizzato in POSIX. Il campo contiene le informazioni separate da virgola relative a nome completo dell'utente, numero telefonico dell'ufficio, numero dell'ufficio, numero telefonico di casa. In molti sistemi è disponibile solo il nome completo dell'utente.
dir	Questo elemento contiene il percorso assoluto alla home directory dell'utente.
shell	L'elemento shell contiene il percorso assoluto alla shell di default per l'utente.

posix_getpwuid

(PHP 3 >= 3.0.13, PHP 4, PHP 5)

posix_getpwuid -- Restituisce le informazioni di un utente dato il suo ID

Descrizione

array posix_getpwuid ( int uid )

La funzione restituisce un array associativo contenente le informazioni sull'utente il cui ID è stato fornito nel parametro uid.

Gli elementi dell'array sono:

Tabella 1. Array delle informazioni utente

Elemento	Descrizione
name	L'elemento name solitamente contiene il nome dell'utente. Questo è un nome corto, di solito meno di 16 caratteri, non il nome reale, completo, dell'utente. Questo dovrebbe essere uguale al parametro `username` passato alla funzione e quindi ridondante.
passwd	L'elemento passwd contiene la password dell'utente in formato criptato. Spesso, ad esempio nei sistemi utilizzano password "shadow", vengono restituiti degli asterischi.
uid	ID dell'utente in formato numerico.
gid	ID del gruppo a cui appartiene l'utente. Utilizzare la funzione posix_getgrgid() per ottenere il nome del gruppo e l'elenco dei suoi membri.
gecos	GECOS è un termine obsoleto che si riferisce a campi del comando finger su sistemi Honeywell. Tuttavia il campo è sopravvissuto ed il suo contenuto è stato formalizzato in POSIX. Il campo contiene le informazioni separate da virgola relative a nome completo dell'utente, numero telefonico dell'ufficio, numero dell'ufficio, numero telefonico di casa. In molti sistemi è disponibile solo il nome completo dell'utente.
dir	Questo elemento contiene il percorso assoluto alla home directory dell'utente.
shell	L'elemento shell contiene il percorso assoluto alla shell di default per l'utente.

Nota: Quando safe-mode è abilitato, PHP controlla che la directory nella quale si sta lavorando, abbia lo stesso UID dello script che è in esecuzione.

posix_mknod

(PHP 5 >= 5.1.0RC1)

posix_mknod -- Create a special or ordinary file (POSIX.1)

Descrizione

bool posix_mknod ( string pathname, int mode [, int major [, int minor]] )

posix_mknod() creates a special or ordinary file.

Elenco dei parametri

pathname: The file to create
mode: This parameter is constructed by a bitwise OR between file type (one of the following constants: POSIX_S_IFREG, POSIX_S_IFCHR, POSIX_S_IFBLK, POSIX_S_IFIFO or POSIX_S_IFSOCK) and permissions.
major: The major device kernel identifier
minor: The minor device kernel identifier

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 1. A posix_mknod() example
<?php $file = '/tmp/tmpfile'; // file name $type = POSIX_S_IFBLOCK; // file type $permissions = 0777; // octal if (!posix_mknod($file, $type | $permissions)) { die('Error ' . posix_get_last_error() . ': ' . posix_strerror(posix_get_last_error())); } ?>

Vedere anche:

posix_mkfifo()

posix_setegid

(PHP 4 >= 4.0.2, PHP 5)

posix_setegid -- Imposta l'effettivo GID per il processo corrente

Descrizione

bool posix_setegid ( int gid )

La funzione imposta l'effettivo ID di gruppo per il processo. Poichè questa è una funzione privilegiata occorre avere gli opportuni privilegi (solitamente di root) per poterla eseguire.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento..

posix_seteuid

(PHP 4 >= 4.0.2, PHP 5)

posix_seteuid -- Imposta l'effettivo UID del processo corrente

Descrizione

bool posix_seteuid ( int uid )

Imposta lo user ID per il processo corrente. Poichè questa è una funzione privilegiata occorre avere gli opportuni privilegi (solitamente di root) per poterla eseguire.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche posix_setgid().

posix_setgid

(PHP 3 >= 3.0.13, PHP 4, PHP 5)

posix_setgid -- Imposta il GID per il processo corrente

Descrizione

bool posix_setgid ( int gid )

bool posix_setuid ( int uid )

La funzione imposta il reale ID di utente per il processo corrente. Questa è una funzione privilegiata e pertanto richiede gli opportuni privilegi (di solito root) per potere essere eseguita.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche posix_setgid().

posix_strerror

(PHP 4 >= 4.2.0, PHP 5)

posix_strerror -- Recupera il messaggio di errore di un dato codice di errore

Descrizione

string posix_strerror ( int errno )

La funzione restiruisce il messaggio di erore POSIX associato aa un dato codice di errore. Se il parametro errno è impostato a 0, viene restituita la stringa "Success". Utilizzare la funzione posix_get_last_error() per ottenere il codice di errore.

Vedere anche posix_get_last_error().

posix_times

(PHP 3 >= 3.0.13, PHP 4, PHP 5)

posix_times -- Restituisce il tempo del processo

Descrizione

array posix_times ( void )

Restituisce una serie di stringhe con le imformazioni sull'utilizzo di CPU del processo. L'indice della matrice è:

ticks - il numero di ticks dall'ultimo rebbot.
utime - user time utilizzato dal processo.
stime - system time utilizzato dal processo.
cutime - user time uutilizzato dal processo e dai suoi figli.
cstime - system time uutilizzato dal processo e dai suoi figli.

Avvertimento

Questa funzione non è affidabile nell'uso, può restituire valori negativi per tempi molto elevati.

posix_ttyname

(PHP 3 >= 3.0.13, PHP 4, PHP 5)

posix_ttyname -- Determina il nome del device per il terminale

Descrizione

string posix_ttyname ( int fd )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

posix_uname

(PHP 3 >= 3.0.10, PHP 4, PHP 5)

posix_uname -- Restituisce il nome del sistema

Descrizione

array posix_uname ( void )

La funzione restituisce un array con informazioni sul sistema. Le chiavi dell'array sono:

sysname - nome del sistema operativo (es. Linux)
nodename - nome del sistema (es. valiant)
release - release del sistema operativo (es. 2.2.10)
version - versione del sistema operativo (es. #4 Tue Jul 20 17:01:36 MEST 1999)
machine - architettura del sistema (es. i586)
domainname - nome del dominio DNS (es. example.com)

La chiave domainname è una estensione GNU e non è parte di POSIX.1, quindi questo campo è disponibile soltanto su sistemi GNU o quando si utilizza la libc di GNU.

Lo standard POSIX richiede di non fare affidamento sul formato dei valori restituiti, ad esempio non aspettarsi di avere sempre tre cifre nel numero di versione.

CXIII. Funzioni per le espressioni regolari (POSIX estesa)

Introduzione

Suggerimento: Il PHP, utilizzando le funzioni PCRE, supporta anche le espressioni regolari con una sintassi compatibile con Perl. Queste funzioni supportano riconoscimenti "pigliatutto", asserzioni, criteri condizionali, e diverse altre caratteristiche che non sono supportate dalla sintassi POSIX estesa.

Avvertimento

Queste funzioni per l'espressioni regolari non sono binary-safe. Le funzioni PCRE lo sono.

In PHP, le espressioni regolari sono utilizzate per complesse manipolazioni di stringhe. Le espressioni regolari utilizzate da PHP sono di tipo POSIX esteso così come definito in POSIX 1003.2. Per una descrizione completa delle espressione regolari POSIX, vedere la pagina del manuale di regex inclusa nella directory di regex nella distribuzione di PHP. Questa è in formato man, pertanto per poterle leggere occorre eseguire man /usr/local/src/regex/regex.7.

Requisiti

Non sono necessarie librerie esterne per utilizzare questo modulo.

Installazione

Avvertimento

Non variare TYPE se non si sa cosa si sta facendo.

Per abilitare il supporto a regex occorre configurare il PHP con --with-regex[=TYPE]. TYPE può essere: system, apache, php. Per default si usa php.

La versione per Windows di PHP ha già compilato il supporto per questo modulo. Non occorre caricare alcun modulo addizionale per potere utilizzare queste funzioni.

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

Questa estensione non definisce alcuna costante.

Esempi

Esempio 1. Esempi di espressione regolare
<?php /* Restituisce vero se "abc" viene trovata ovunque in $string. */ ereg("abc", $string); /* Restituisce vero se "abc" viene trovata all'inizio di $string. */ ereg("^abc", $string); /* Restituisce vero se "abc" viene trovata alla fine di $string. */ ereg("abc$", $string); /* Restituisce vero se il browser è Netscape 2, 3 oppure MSIE 3. */ eregi("(ozilla.[23]|MSIE.3)", $HTTP_USER_AGENT); /* Posizione tre parole separate da spazio in $regs[1], $regs[2] e $regs[3]. */ ereg("([[:alnum:]]+) ([[:alnum:]]+) ([[:alnum:]]+)", $string, $regs); /* Posiziona il tag <br /> all'inizio di $string. */ $string = ereg_replace("^", "<br />", $string); /* Posiziona il tag <br /> alla fine di $string. */ $string = ereg_replace("$", "<br />", $string); /* Toglie ogni carattere di invio da $string. */ $string = ereg_replace("\n", "", $string); ?>

Vedere anche:

Per maggiori dettagli sulle espressioni regolari compatibili con Perl vedere il capitolo sulle funzioni PCRE. La funzione fnmatch() fornisce il riconoscimento dei caratteri jolly tipici della linea di comando.

Sommario
ereg_replace -- Sostituzioni con espressioni regolari
ereg -- Riconoscimento di espressione regolare
eregi_replace -- Sostituzioni con espressioni regolari senza distinzione tra maiuscole e minuscole
eregi -- Riconoscimento di espressioni regolari senza distinzione tra maiuscole e minuscole
split -- Suddivide una stringa in una matrice utilizzando le espressioni regolari
spliti -- Suddivide una stringa in una matrice usando le espressioni regolari senza distinguere tra maiuscole e minuscole
sql_regcase -- Genera una espressione regolare per riconoscimenti senza distinguere tra maiuscole e minuscole

ereg_replace

(PHP 3, PHP 4, PHP 5)

ereg_replace -- Sostituzioni con espressioni regolari

Descrizione

string ereg_replace ( string espressione_regolare, string testo_sostitutivo, string stringa )

La funzione ricerca all'interno del parametro stringa sottostringhe che incrocino con le condizioni specificate in espressione_regolare. Quando sono trovate, queste vengono sostituite con il testo specificato in testo_sostitutivo.

La funzione restituisce la stringa modificata. (Ciò implica che se non ci sono sottostringhe che soddisfino l' espressione regolare, la funzione restituisce la stringa originaria).

Se in espressione_regolare si specificano delle sottostringhe utilizzando le parentesi, anche nel campo testo_sostitutivo si possono specificare delle sottostringhe di formato \\digit, che saranno sostituite dalle stringhe soddisfacenti la digit'esima condizione posta tra parentesi; \\0 indica l'intera stringa. La funzione prevede che si possano utlizzare fino a nove sottostringhe. E' previsto che le parentesi siano nidificate, in questo caso il conteggio si basa sulle parentesi aperte.

Se nessuna parte di stringa viene riconosciuta, il parametro viene restituito invariato.

Come esempio il seguente frammento di codice visualizzerà la frase "Questo fu un test" tre volte:

Esempio 1. ereg_replace() esempio
<?php $stringa = "Questo è un test"; echo ereg_replace(" è", " fu", $stringa); echo ereg_replace("( )è", "\\1fu", $stringa); echo ereg_replace("(( )è)", "\\2fu", $stringa); ?>

Un aspetto a cui occorre prestare attenzione riguarda l'uso di numero intero per il parametro testo_sostitutivo, si potrebbero ottenere risultati diversi da quanto atteso. Questo accade perchè la funzione ereg_replace() interpreta il numero come posizione ordinale di un carattere comportandosi di conseguenza. Ad esempio:

Esempio 2. ereg_replace() esempio
<?php /* Questo non si comporta come atteso. */ $num = 4; $stringa = "Questa stringa ha quattro parole."; $stringa = ereg_replace('quattro', $num, $stringa); echo $stringa; /* Risultato: 'Questa stringa ha parole.' */ /* Questo funziona. */ $num = '4'; $stringa = "Questa stringa ha quattro parole."; $stringa = ereg_replace('quattro', $num, $stringa); echo $stringa; /* Risultato: 'Questa stringa ha 4 parole' */ ?>

Esempio 3. Sostituzione di URL
<?php $testo = ereg_replace("[[:alpha:]]+://[^<>[:space:]]+[[:alnum:]/]", "<a href=\"\\0\">\\0</a>", $testo); ?>

Suggerimento: Poichè utilizza espressioni regolari con sintassi compatibile con Perl, preg_replace(), è spesso una alternativa più veloce a ereg_replace().

Vedere anche ereg(), eregi(), eregi_replace(), str_replace() e preg_match().

ereg

(PHP 3, PHP 4, PHP 5)

ereg -- Riconoscimento di espressione regolare

Descrizione

int ereg ( string epressione_regolare, string stringa [, array &regs] )

Nota: Poichè utilizza espressioni regolari con sintassi compatibile con PERL, preg_match(), è spesso una alternativa più veloce a ereg().

Ricerca in stringa testi che possano incrociarsi con l'espressione regolare indicata in espressione_regolare distinguendo tra lettere minuscole e maiuscole.

Se le parti di testo poste tra parentesi nel campo espressione_regolare sono incontrate nella stringa e la funzione viene chiamata utilizzando il terzo parametro regs, il testo riconosciuto sarà memorizzato nella matrice regs. L'indice 1, $regs[1], conterrà la sottostringa che parte dalla prima parentesi sinistra; $regs[2] conterrà la sottostringa a partire dalla seconda e così via. L'indice 0, $regs[0], conterrà la copia completa della stringa riconosciuta.

Nota: Fino alla versione di PHP 4.1.0 compresa, $regs conterrà esattamente 10 elementi, anche se il numero delle stringhe riconosciute sia maggiore o minore di 10. Ciò non limita ereg() nella ricerca di più sottostringhe. Se non si riconoscono testi, $regs non sarà modificato da ereg().

array split ( string espressione_regolare, string stringa [, int limite] )

Suggerimento: Poichè utilizza espressioni regolari con sintassi compatibile con Perl, preg_split(), è spesso una alternativa più veloce a split(). Se non si ha necessità delle capacità delle espressioni regolari, è più veloce l'utilizzo di explode(), che non richiede l'overhead del motore delle espressioni regolari.

La funzione restituisce una matrice di stringhe che sono delle sottostringhe del parametro stringa. Queste sono ottenute suddividendo il parametro secondo i limiti indicati dal parametro sensibile alle maiuscole espressione_regolare. Se viene specificato il parametro limite, la funzione restituisce una matrice con un numero di elementi al massimo pari a limite. L'ultimo elemento della matrice contiene la parte restante del parametro stringa fornito. Se si verificano errori la funzione split() restituisce FALSE.

Esempio di come estrapolare i primi 4 campi da una linea del file /etc/passwd:

Esempio 1. Esempio di split()
<?php list($user, $pass, $uid, $gid, $extra) = split(":", $passwd_line, 5); ?>

Se nella stringa passata vi sono n occorrenze del parametro espressione_regolare, la matrice restituita conterrà n+1 elementi. Invece, nel caso in cui non vi siano occorrenze della espressione_regolare, la matrice restituita conterrà un solo elemento. Ovviamente questo è valido anche nel caso in cui il parametro stringa è vuoto.

Nell'esempio che segue, si vedrà come analizzare una data il cui testo può contenere barre, punti o trattini:

Esempio 2. split() esempio
// Delimitatori di testo: barre, punti, trattini $data = "04/30/1973"; list ($mese, $giorno, $anno) = split ('[/.-]', $data); echo "Mese: $mese; Giorno: $giorno; Anno: $anno<br>\n"; ?>

Gli utenti che cercano un modo di emulare il comportamento di Perl @chars = split('', $str), sono rimandati agli esempi di preg_split().

Occorre fare attenzione al fatto che il parametro espressione_regolare è una espressione regolare e, pertanto, se si devono riconoscere caratteri che sono considerati speciali per le espressioni regolari, occorre codificarli con i caratteri di escape. Se si ritiene che la funzione split () ( o anche le altre funzioni derivate da regex ) si comportino in modo anomalo, è opportuno leggere il file regex.7, incluso nella cartella regex/ della distribuzione di PHP. Questo file è nel formato del manuale di unix (man), pertanto per visualizzarlo occorre eseguire il comando man /usr/local/src/regex/regex.7.

Vedere anche: preg_split(), spliti(), explode(), implode(), chunk_split() e wordwrap().

spliti

(PHP 4 >= 4.0.1, PHP 5)

spliti -- Suddivide una stringa in una matrice usando le espressioni regolari senza distinguere tra maiuscole e minuscole

Descrizione

array spliti ( string pattern, string string [, int limit] )

Questa funzione ha un comportamento identico a split() tranne che per il fatto di non distinguere tra lettere maiuscole e minuscole. characters.

Il seguente esempio suddivide una stringa utilizzando la lettera 'a' come separatore:
Esempio 1. Esempio di uso di spliti()
<?php $string = "aBBBaCCCADDDaEEEaGGGA"; $chunks = spliti ("a", $string, 5); print_r($chunks); ?>
Il precedente esempio visualizzerà:
Array ( [0] => [1] => BBB [2] => CCC [3] => DDD [4] => EEEaGGGA )

Vedere anche preg_split(), split(), explode(), e implode().

sql_regcase

(PHP 3, PHP 4, PHP 5)

sql_regcase -- Genera una espressione regolare per riconoscimenti senza distinguere tra maiuscole e minuscole

Descrizione

string sql_regcase ( string stringa )

La funzione restituisce una espressione regolare che sia in grado di riconoscere il parametro stringa, a prescindere dalle lettere maiuscole minuscole. L'espressione regolare restituita corrisponde a stringa con ciascun carattere alfabetico riportato tra parentesi. Ogni parentesi contiene il singolo carattere in maiuscolo ed in minuscolo. I rimanenti caratteri sono riportati immutati.
Esempio 1. sql_regcase() esempio
<?php echo sql_regcase("Foo bar"); ?>
Il precedente esempio visualizzerà:
[Ff][Oo][Oo] - [Bb][Aa][Rr].

Questa funzione torna utile quando si devono ottenere espressioni regolari non distinguono tra lettere maiuscole e minuscole da passare a prodotti che supportano espressioni regolari che distinguono il tipo di lettera.

CXIV. Funzioni PostgreSQL

Introduzione

Il database PostgreSQL è un prodotto OpenSource ed è disponibile gratuitamente. Postgres, sviluppato originariamente nel Dipartimento di Informatica dell'Università di Berkeley, ha anticipato molti dei concetti su oggetti e relazioni che ora stanno diventando disponibili in alcuni database commerciali. Postgres fornisce supporto per il linguaggio SQL/92/SQL99, transazioni, integrità referenziale, stored procedures ed estensibilità dei tipi. PostgreSQL è un discendente open source dell'originario codice di Berkeley.

Requisiti

Per utilizzare il supporto a PostgreSQL, occorre PostgreSQL 6.5 o versioni più recenti. PostgreSQL 7.0 o successivi permettono di abilitare tutte le funzionalità di questo modulo. PostgreSQL ammette molte codifiche di carattere, tra cui la codifica multibyte. La versione corrente e maggiori informazioni su PostgreSQL sono disponibili su http://www.postgresql.org/ e http://techdocs.postgresql.org/.

Installazione

In order to enable PostgreSQL support, --with-pgsql[=DIR] is required when you compile PHP. DIR is the PostgreSQL base install directory, defaults to /usr/local/pgsql. If shared object module is available, PostgreSQL module may be loaded using extension directive in php.ini or dl() function.

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

Tabella 1. PostgreSQL configuration options

Name	Default	Changeable	Changelog
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	Available since PHP 4.2.0.
pgsql.ignore_notice	"0"	PHP_INI_ALL	Available since PHP 4.3.0.
pgsql.log_notice	"0"	PHP_INI_ALL	Available since PHP 4.3.0.

Per maggiori dettagli sulle costanti PHP_INI_* vedere Appendice G.

Breve descrizione dei parametri di configurazione.

pgsql.allow_persistent boolean: Whether to allow persistent Postgres connections.
pgsql.max_persistent integer: The maximum number of persistent Postgres connections per process.
pgsql.max_links integer: The maximum number of Postgres connections per process, including persistent connections.
pgsql.auto_reset_persistent integer: Detect broken persistent links with pg_pconnect(). Needs a little overhead.
pgsql.ignore_notice integer: Whether or not to ignore PostgreSQL backend notices.
pgsql.log_notice integer: Whether or not to log PostgreSQL backends notice messages. The PHP directive pgsql.ignore_notice must be off in order to log notice messages.

Utilizzo e suggerimenti

Avvertimento

L'utilizzo del modulo PostgreSQL con PHP 4.0.6 non è raccomandato a causa di un bug nella gestione dei messaggi. Si usi PHP 4.1.0 o successivi.

Avvertimento

I nomi delle funzioni relative a PostgreSQL verranno cambiate a partire dalla versione 4.2.0 per conformarsi agli standard di sviluppo attuali. La maggior parte dei nuovi nomi avrà underscore aggiuntivi, per esempio pg_lo_open(). Alcune funzioni verranno rinominate per dare consistenza. Per esempio pg_exec() diventerà pg_query(). I vecchi nomi potranno essere usati nella versione 4.2.0 e in alcune versioni successive alla 4.2.0, ma potranno essere cancellati in futuro.

Tabella 2. Nomi di funzione cambiati

Vecchio nome	Nuovo nome
pg_exec()	pg_query()
pg_getlastoid()	pg_last_oid()
pg_cmdtuples()	pg_affected_rows()
pg_numrows()	pg_num_rows()
pg_numfields()	pg_num_fields()
pg_fieldname()	pg_field_name()
pg_fieldsize()	pg_field_size()
pg_fieldnum()	pg_field_num()
pg_fieldprtlen()	pg_field_prtlen()
pg_fieldisnull()	pg_field_is_null()
pg_freeresult()	pg_free_result()
pg_result()	pg_fetch_result()
pg_loreadall()	pg_lo_read_all()
pg_locreate()	pg_lo_create()
pg_lounlink()	pg_lo_unlink()
pg_loopen()	pg_lo_open()
pg_loclose()	pg_lo_close()
pg_loread()	pg_lo_read()
pg_lowrite()	pg_lo_write()
pg_loimport()	pg_lo_import()
pg_loexport()	pg_lo_export()

La vecchia sintassi di pg_connect()/pg_pconnect() sarà deprecata per supportare, in futuro, connessioni asincrone. Si usi una stringa di connessione con pg_connect() e pg_pconnect().

Non tutte le funzioni sono supportate su tutte le architetture. Dipende dalla versione di libpq (L'interfaccia Client C per PostgreSQL) e da come libpq è compilato. Se c'è una funzione mancante, libpq non supporta la feature richiesta per quella funzione.

È importante usare versioni di libpq più recenti rispetto al Server PostgreSQL al quale ci si vuole collegare. Se si usa una versione di libpq più vecchia rispetto al Server PostgreSQL al quale ci si vuole collegare, si andrà probabilmente incontro a problemi.

Fin dalla versione 6.3 (03/02/1998) PostgreSQL usa gli unix domain socket di default. La porta TCP, di default, NON verrà aperta. La tabella sottostante descrive queste nuove possibilità di connessione. Questo socket può essere trovato in /tmp/.s.PGSQL.5432. Questa opzione può venire abilitata con la flag '-i' da postmaster e il suo significato è: "ascolta i socket TCP/IP così come gli Unix domain socket".

Tabella 3. Postmaster e PHP

Postmaster	PHP	Status
postmaster &	pg_connect("dbname=NomeMioDatabase");	OK
postmaster -i &	pg_connect("dbname=NomeMioDatabase");	OK
postmaster &	pg_connect("host=localhost dbname=NomeMioDatabase");	Unable to connect to PostgreSQL server: connectDB() failed: Is the postmaster running and accepting TCP/IP (with -i) connection at 'localhost' on port '5432'? in /path/to/file.php on line 20.
postmaster -i &	pg_connect("host=localhost dbname=NomeMioDatabase");	OK

Si può stabilire una connessione al server PostgreSQL usando le seguenti coppie di valori impostate nella stringa di comando: $conn = pg_connect("host=IlMioHost port=LaMiaPorta tty=myTTY options=LeMieOpzioni dbname=IlMioDB user=IlMioUtente password=LaMiaPassword ");

L'uso della sintassi in uso precedentemente: $conn = pg_connect ("host", "port", "options", "tty", "dbname") è deprecato.

Le variabili d'ambiente modificano il comportamento server/client di PostgreSQL. Per esempio, il modulo PostgreSQL si baserà sulla variabile PGHOST quando il nome dell'host è omesso nella stringa di connessione. Le variabili d'ambiente riconosciute sono diverse da versione a versione. Consultare il Manuale del Programmatore PostgreSQL (libpq - Variabili d'Ambiente) per ulteriori dettagli.

Assicurarsi di aver impostato le variabili d'ambiente per l'utente appropriato. Usare $_ENV o getenv() per controllare quali variabili d'ambiente sono disponibili al processo corrente.

Esempio 1. Impostazione dei parametri di default

PGHOST=pgsql.example.com
PGPORT=7890
PGDATABASE=web-system
PGUSER=web-user
PGPASSWORD=segreta
PGDATESTYLE=ISO
PGTZ=JST
PGCLIENTENCODING=EUC-JP

export PGHOST PGPORT PGDATABASE PGUSER PGPASSWORD PGDATESTYLE PGTZ PGCLIENTENCODING

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

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 then 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_POSITION field, but it is used when the cursor position refers to an internally generated command rather than the one submitted by the client. The PG_DIAG_INTERNAL_QUERY field 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_DEFAULT (integer): Passed to pg_convert(). Ignore conversion of NULL into SQL NOT NULL columns.

Esempi

A partire da PostgreSQL 7.1.0, il tipo di dato text ha 1GB come dimensione massima. Nelle versioni più vecchie di PostgreSQL il tipo di dato text è limitato dalla dimensione del block. (Default 8KB. Massimo 32KB, specificato al momento della compilazione)

Per usare l'interfaccia large object (lo), è necessario includerla entro un blocco di una transazione. Un blocco di transazione inizia con un comando SQL BEGIN e se la transazione è stata valida, termina con COMMIT o END. Se la transazione fallisce, essa deve venire chiusa con ROLLBACK o ABORT.
Esempio 2. Utilizzare Large Objects
<?php $database = pg_connect ("dbname=jacarta"); pg_query ($database, "begin"); $oid = pg_lo_create ($database); echo "$oid\n"; $handle = pg_lo_open ($database, $oid, "w"); echo "$handle\n"; pg_lo_write ($handle, "dati large object"); pg_lo_close ($handle); pg_query ($database, "commit"); ?>
Non chiudere la risorsa di connessione prima di aver chiuso la risorsa large object.

Sommario
pg_affected_rows -- Restituisce il numero delle tuple coinvolte dall'ultimo comando
pg_cancel_query -- Annulla una query asincrona
pg_client_encoding -- Restituisce la codifica caratteri del client
pg_close -- Chiude una connessione PostgreSQL
pg_connect -- Stabilisce una connessione PostgreSQL
pg_connection_busy -- Riferisce se una connessione è occupata o meno
pg_connection_reset -- Rpristina la connessione (riconnette)
pg_connection_status -- Restituisce lo stato di una connessione
pg_convert -- Converte i valori di un array associativo in una forma compatibile con i comandi SQL.
pg_copy_from -- Inserisce le tuple in una tabella prendendole da un array
pg_copy_to -- Copia una tabella in un array
pg_dbname -- Restituisce il nome del database
pg_delete -- Cancella le tuple.
pg_end_copy -- Esegue una sincronizzazione con il backend PostgreSQL
pg_escape_bytea -- Aggiunge le sequenze di escape ai dati binari nel tipo bytea
pg_escape_string -- Aggiunge le sequenze di escape nei tipi text/char
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 -- Carica tutte le tuple in un array
pg_fetch_array -- Carica una tupla in un array
pg_fetch_assoc -- Fetch a row as an array
pg_fetch_object -- Carica una tupla in un oggetto
pg_fetch_result -- Restituisce i valori da una risorsa di risultato
pg_fetch_row -- Carica una tupla in un array
pg_field_is_null -- Verifica se un campo è NULL
pg_field_name -- Restituisce il nome di un campo
pg_field_num -- Restituisce la posizione del campo specificato
pg_field_prtlen -- Restituisce la lunghezza "stampabile" di un valore
pg_field_size -- Restituisce la reale dimensione di memorizzazione del campo
pg_field_type_oid -- Returns the type ID (OID) for the corresponding field number
pg_field_type -- Restituisce il nome del tipo del campo specificato
pg_free_result -- Libera la memoria allocata per i risultati
pg_get_notify -- Ping database connection
pg_get_pid -- Ping database connection
pg_get_result -- Recupera i risultati di una query asincrona
pg_host -- Restituisce il nome dell'host associato alla connessione
pg_insert -- Inserisce un array in una tabella.
pg_last_error -- Restituisce l'ultimo messaggio d'errore di una connessione
pg_last_notice -- Restituisce l'ultimo messaggio di notifica dal server PostgreSQL
pg_last_oid -- Restituisce l'oid dell'ultimo oggetto
pg_lo_close -- Chiude un large object
pg_lo_create -- Crea un large object
pg_lo_export -- Esporta un large object salvandolo su un file
pg_lo_import -- Importa un large object da un file
pg_lo_open -- Apre un large object
pg_lo_read_all -- Legge interamente un large object e lo manda direttamente al browser
pg_lo_read -- Legge un large object
pg_lo_seek -- Ricerca la posizione di un large object
pg_lo_tell -- Restituisce la posizione attuale in un large object
pg_lo_unlink -- Cancella un large object
pg_lo_write -- Scrive un large object
pg_meta_data -- Ottiene la definizione di una tabella.
pg_num_fields -- Restituisce il numero di campi
pg_num_rows -- Restituiscein numero di tuple
pg_options -- Estrae le opzioni associate alla connessione
pg_parameter_status -- Looks up a current parameter setting of the server.
pg_pconnect -- Open a persistent PostgreSQL connection
pg_ping -- Ping database connection
pg_port -- Restituisce il numero di porta associato alla connessione
pg_prepare -- Submits a request to create a prepared statement with the given parameters, and waits for completion.
pg_put_line -- Invia una stringa terminata da NULL al backend 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 -- Esegue una query
pg_result_error_field -- Returns an individual field of an error report.
pg_result_error -- Restituisce i messaggio di errore associato al risultato
pg_result_seek -- Set internal row offset in result resource
pg_result_status -- Recupera lo stato del risultato di una query
pg_select -- Seleziona delle tuple.
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 -- Invia una query in modo asincrono
pg_set_client_encoding -- Imposta la codifica del client
pg_set_error_verbosity -- Determines the verbosity of messages returned by pg_last_error() and pg_result_error().
pg_trace -- iAbilita il tracciamento di una connessione PostgreSQL
pg_transaction_status -- Returns the current in-transaction status of the server.
pg_tty -- Restituisce il nome della tty associata alla connessione
pg_unescape_bytea -- Escape binary for bytea type
pg_untrace -- Disabilita il tracciamento di una connessione PostgreSQL
pg_update -- Modifica le tuple della tabella
pg_version -- Returns an array with client, protocol and server version (when available)

pg_affected_rows

(PHP 4 >= 4.2.0, PHP 5)

pg_affected_rows -- Restituisce il numero delle tuple coinvolte dall'ultimo comando

Descrizione

int pg_affected_rows ( resource risultato )

pg_affected_rows() restituisce il numero di tuple (istanze/record/righe) coinvolte dalle query INSERT, UPDATE, e DELETE eseguite da pg_query(). Se nessuna tupla è stata modificata da questa funzione, restituisce 0.
Esempio 1. pg_affected_rows()
<?php $risultato = pg_query ($conn, "INSERT INTO editore VALUES ('Autore')"); $numtuple = pg_affected_rows ($risultato); echo $numtuple . " tuple modificate."; ?>

Nota: Questa funzione si chiamava pg_cmdtuples().

Vedere anche pg_query() e pg_num_rows().

pg_cancel_query

(PHP 4 >= 4.2.0, PHP 5)

pg_cancel_query -- Annulla una query asincrona

Descrizione

pg_convert() controlla e converte arrayassoc rendendolo compatibile con i comandi SQL.

Nota: Questa funzione è sperimentale.

pg_delete

(PHP 4 >= 4.3.0, PHP 5)

pg_delete -- Cancella le tuple.

Descrizione

mixed pg_delete ( resource connessione, string nometabella, array arrayassoc [, int opzioni] )

pg_delete() cancella le tuple indicate dalle condizioni specificate da arrayassoc composto da campo=>valore. Se opzioni è specificato, pg_convert() viene applicata a arrayassoc con l'opzione data.

Esempio 1. pg_delete

<?php 
    $db = pg_connect ('dbname=foo');
    // Questo è sicuro, dal momento che $_POST è convertita automaticamente
    $ris = pg_delete($db, 'post_log', $_POST);
    if ($ris) {
       echo "I dati inviati in POST sono stati cancellati: $ris\n";
    }
    else {
        echo "L'utente ha inviato dati sbagliati\n";
    }
?>

Nota: Questa funzione è sperimentale.

Nota: Questa funzione richiede PostgreSQL 7.2 o successivi.

Vedere anche pg_escape_bytea()

pg_execute

(PHP 5 >= 5.1.0RC1)

pg_execute -- Sends a request to execute a prepared statement with given parameters, and waits for the result.

Descrizione

resource pg_execute ( resource connection, string stmtname, array params )

resource pg_execute ( 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.

Elenco dei parametri

connection: PostgreSQL database connection resource. When connection is 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.

Valori restituiti

A query result resource on success, or FALSE on failure.

Esempi

Esempio 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")); ?>

Vedere anche:

pg_prepare()

pg_send_prepare()

pg_query_params()

pg_fetch_all_columns

(PHP 5 >= 5.1.0RC1)

pg_fetch_all_columns -- Fetches all rows in a particular result column as an array

Descrizione

array pg_fetch_all_columns ( resource result [, int column] )

pg_fetch_all_columns() returns an array that contains all rows (records) in a particular column of the result resource.

Nota: This function sets NULL fields to PHP NULL value.

Elenco dei parametri

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.

Valori restituiti

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.

Esempi

Esempio 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); ?>

Vedere anche:

pg_fetch_all()

pg_fetch_all

(PHP 4 >= 4.3.0, PHP 5)

pg_fetch_all -- Carica tutte le tuple in un array

Descrizione

array pg_fetch_all ( resource risultato [, int tupla] )

pg_fetch_all() restituisce un array che contiene tutte le tuple (righe/record) contenuti nella risorsa risultato. Restituisce FALSE se non ci sono tuple.

Vedere anche pg_fetch_row(), pg_fetch_array(), pg_fetch_object() e pg_fetch_result().

Esempio 1. PostgreSQL fetch array
<?php $conn = pg_pconnect ("dbname=publisher"); if (!$conn) { echo "E' avvenuto un errore.\n"; exit; } $result = pg_query ($conn, "SELECT * FROM authors"); if (!$result) { echo "E' avvenuto un errore.\n"; exit; } $arr = pg_fetch_all ($result, 0, PGSQL_NUM); var_dump($arr); ?>

pg_fetch_array

(PHP 3 >= 3.0.1, PHP 4, PHP 5)

pg_fetch_array -- Carica una tupla in un array

Descrizione

array pg_fetch_array ( resource result [, int tupla [, int tipo_risultato]] )

pg_fetch_array() restituisce un array che corrisponde alla riga caricata (tuple/record). Restituisce FALSE se non ci sono più righe.

pg_fetch_array() è una versione estesa di pg_fetch_row(). Oltre a salvare i dati in un array con indici numerici, li salva pure in un array associativo, utilizzando i nomi dei campi come chiave.

tupla è il numero della riga (record) che deve essere caricata. La prima riga è la 0.

tipo_risultato è un parametro opzionale che controlla come il risultato viene restituito. result_type è una costante e può assumere i seguenti valori: PGSQL_ASSOC, PGSQL_NUM, e PGSQL_BOTH. pg_fetch_array() restituisce un array associativo con il nome del campo come chiave con PGSQL_ASSOC, oppure l'indice del campo con PGSQL_NUM o entrambi con PGSQL_BOTH. Il default è PGSQL_BOTH.

Nota: tipo_risultato è stato aggiunto nel PHP 4.0.

pg_fetch_array() NON è più lento di pg_fetch_row(), inoltre è più facile da usare.

Esempio 1. PostgreSQL fetch array
<?php $conn = pg_pconnect ("dbname=editori"); if (!$conn) { echo "Si è verificato un errore.\n"; exit; } $risultato = pg_query ($conn, "SELECT * FROM autori"); if (!$risultato) { echo "Si è verificato un errore.\n"; exit; } $arr = pg_fetch_array ($risultato, 0, PGSQL_NUM); echo $arr[0] . " <- array\n"; $arr = pg_fetch_array ($risultato, 1, PGSQL_ASSOC); echo $arr["autore"] . " <- array\n"; ?>

Vedere anche pg_fetch_row(), pg_fetch_object() e pg_fetch_result().

Nota: Dalla versione 4.1.0, tupla è opzionale. La chiamata a pg_fetch_array() incrementa di 1 il puntatore alle tuple.

pg_fetch_assoc

(PHP 4 >= 4.3.0, PHP 5)

pg_fetch_assoc -- Fetch a row as an array

Description

array pg_fetch_assoc ( resource result [, int row] )

pg_fetch_assoc() returns an associative array that corresponds to the fetched row (tuples/records). It returns FALSE, if there are no more rows.

pg_fetch_assoc() is an extended version of pg_fetch_row(). In addition to storing the data in the numeric indices (field index) to the result array, it also stores the data in associative indices (field name) by default.

row is row (record) number to be retrieved. First row is 0.

pg_fetch_assoc() is NOT significantly slower than using pg_fetch_row(), while it provides a significant ease of use.

See also pg_fetch_row(), pg_fetch_array(), pg_fetch_assoc(), pg_fetch_object() and pg_fetch_result().

Esempio 1. PostgreSQL fetch array
<?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_assoc ($result, 1, PGSQL_ASSOC); echo $arr["author"] . " <- array\n"; ?>

pg_fetch_object

(PHP 3 >= 3.0.1, PHP 4, PHP 5)

pg_fetch_object -- Carica una tupla in un oggetto

Descrizione

object pg_fetch_object ( resource result [, int tupla [, int tipo_risultato]] )

pg_fetch_object() restituisce un oggetto avente le proprietà che corrispondono alla tupla scaricata. Restituisce FALSE se non ci sono più tuple o in caso di errore.

pg_fetch_object() è simile a pg_fetch_array(), con una differenza - viene restituito un oggetto invece che un array. Indirettamente, questo significa che si può accedere ai dati solo attraverso i nomi dei campi, e non attraverso i loro indici numerici (i nomi delle proprietà non possono essere numeri).

tupla è il numero della riga (record) da caricare. La prima tupla è la numero 0.

Per quanto riguarda la velocità di esecuzione, questa funzione è identica a pg_fetch_array(), ed è veloce quasi quanto pg_fetch_row() (la differenza è trascurabile).

Nota: Dalla versione 4.1.0, tupla è opzionale.
Dalla versione 4.3.0, tipo_risultato è di default a PGSQL_ASSOC mentre il default delle versioni precedenti era PGSQL_BOTH. La proprietà numerica è inutile, dal momento che un nome di proprietà numerico non è valido in PHP.
tipo_risultato potrebbe essere abbandonato nelle versioni future.

Esempio 1. Postgres fetch object
<?php $database = "verlag"; $db_conn = pg_connect ("host=localhost port=5432 dbname=$database"); if (!$db_conn): ?> <H1>Failed connecting to postgres database <?php echo $database ?></H1> <?php exit; endif; $qu = pg_exec ($db_conn, "SELECT * FROM verlag ORDER BY autor"); $row = 0; // postgres needs a row counter other dbs might not while ($data = pg_fetch_object ($qu, $row)) { echo $data->autor." ("; echo $data->jahr ."): "; echo $data->titel."<BR>"; $row++; } ?> <PRE> <?php $fields[] = Array ("autor", "Author"); $fields[] = Array ("jahr", " Year"); $fields[] = Array ("titel", " Title"); $row= 0; // postgres needs a row counter other dbs might not while ($data = pg_fetch_object ($qu, $row)) { echo "----------\n"; reset ($fields); while (list (,$item) = each ($fields)): echo $item[1].": ".$data->$item[0]."\n"; endwhile; $row++; } echo "----------\n"; ?> </PRE> <?php pg_freeresult ($qu); pg_close ($db_conn); ?>

Vedere anche pg_query(), pg_fetch_array(), pg_fetch_row() e pg_fetch_result().

Nota: Dalla versione 4.1.0, row è diventato opzionale. La chiamata alla pg_fetch_object() incrementa di 1 il contatore di riga interno.

pg_fetch_result

(PHP 4 >= 4.2.0, PHP 5)

pg_fetch_result -- Restituisce i valori da una risorsa di risultato

Descrizione

mixed pg_fetch_result ( resource risultato, int tupla, mixed campo )

pg_fetch_result() restituisce i valori da una risorsa risultato ottenuta mediante pg_query(). tupla è un intero. campo è il nome del campo (stringa) o l'indice del campo (intero). I parametri tupla e campo indicano quale cella nella tabella risultante va restituita. La numerazione delle tuple parte da 0. Invece di indicare il nome del campo, si può usare l'indice del campo sotto forma di numero senza virgolette. Gli indici dei campo partono da 0.

PostgreSQL ha molti tipi di dato e solo quelli più usati sono supportati direttamente da questa funzione. Tutti gli integer, sono restituiti come valori integer. Tutti i float, e i tipi real sono restituiti come valori float. Boolean è restituito come "t" o "f". Tutti gli altri tipi, compresi gli array, sono restituiti come stringhe formattate nello stesso modo di default che si puo vedere nel programma psql.

pg_fetch_row

(PHP 3 >= 3.0.1, PHP 4, PHP 5)

pg_fetch_row -- Carica una tupla in un array

Descrizione

array pg_fetch_row ( resource result, int tupla )

pg_fetch_row() carica un record dal risultato della query associato alla risorsa identificata da result. La riga (record) è restituia sotto form di array. Ogni campo è identificato da un indice numerico, che inizia da 0.

Restituisce un array che corrisponde alla riga caricata, oppure FALSE se non ci sono altre tuple.

Esempio 1. Postgres fetch row
<?php $conn = pg_pconnect ("dbname=editori"); if (!$conn) { echo "Si è verificato un errore.\n"; exit; } $result = pg_query ($conn, "SELECT * FROM autori"); if (!$rrisultato) { echo "Si è verificato un errore.\n"; exit; } while ($row = pg_fetch_row($risultato, $i)) { for ($j=0; $j < count($row); $j++) { echo "$row[$j] "; } echo "<BR>"; } ?>

Vedere anche pg_query(), pg_fetch_array(), pg_fetch_object() e pg_fetch_result().

Nota: Dalla versione 4.1.0, row è opzionale. La chiamata a pg_fetch_row() incrementa il puntatore alle tuple di 1.

pg_field_is_null

(PHP 4 >= 4.2.0, PHP 5)

pg_field_is_null -- Verifica se un campo è NULL

Descrizione

int pg_field_is_null ( resource risultato, int tupla, mixed campo )

pg_field_is_null() controlla se un campo è NULL o meno. Restituisce se il campo nella tupla data è NULL. Restituisce 0 se il campo nella tupla NON è NULL. Il campo può essere specificato con un indice di colonna (numero) o come un nome di campo (stringa). La numerazione comincia da 0.

Nota: Questa funzione si chiamava g_fieldisnull().

pg_field_name

(PHP 4 >= 4.2.0, PHP 5)

pg_field_name -- Restituisce il nome di un campo

Descrizione

string pg_field_name ( resource risultato, int numero_campo )

pg_field_name() restituisce il nome del campo che occupa la posizione indicata da numero_campo, rispetto alla risorsa risultato. La numerazione dei campi parte da 0.

Nota: Questa funzione si chiamava pg_fieldname().

Vedere anche pg_field_num().

pg_field_num

(PHP 4 >= 4.2.0, PHP 5)

pg_field_num -- Restituisce la posizione del campo specificato

Descrizione

int pg_field_num ( resource risultato, string nome_campo )

pg_field_num() restituisce il numero della colonna che corrisponde al campo nome_campo nella risorsa PostgreSQL risultato spacificata. La numerazione dei campi parte da 0. Questa funzione restituisce -1 in caso di errore.

Nota: Questa funzione si chiamava pg_fieldnum().

Vedere anche pg_field_name().

pg_field_prtlen

(PHP 4 >= 4.2.0, PHP 5)

pg_field_prtlen -- Restituisce la lunghezza "stampabile" di un valore

Descrizione

int pg_field_prtlen ( resource risultato, int indice_tupla, string nome_campo )

pg_field_prtlen() restituisce la reale lunghezza (numero di caratteri) di uno specifico valore in un risultato di PostgreSQL. La numerazione delle tuple parte da 0. Questa funzione restituisce -1 in caso di errore.

Nota: Questa funzione si chiamava pg_field_prtlen().

Vedere anche pg_field_size().

pg_field_size

(PHP 4 >= 4.2.0, PHP 5)

pg_field_size -- Restituisce la reale dimensione di memorizzazione del campo

Descrizione

int pg_field_size ( resource risultato, int indice_campo )

pg_field_size() restituisce la dimensione di memorizzazione (in bytes) del campo indicato all'interno di risultato. La numerazione dei campi comincia da 0. Una dimension del campo di -1 indica un campo a lunghezza variabile. Questa funzione restituisce FALSE in caso di errore.

Nota: Questa funzione si chiamava pg_fieldsize().

Vedere anche pg_field_prtlen() e pg_field_type().

pg_field_type_oid

(PHP 5 >= 5.1.0RC1)

pg_field_type_oid -- Returns the type ID (OID) for the corresponding field number

Descrizione

int pg_field_type_oid ( resource 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.

Nota: 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.

Elenco dei parametri

result: PostgreSQL query result resource, returned by pg_query(), pg_query_params() or pg_execute() (among others).
field_number: Field number, starting from 0.

Valori restituiti

The OID of the field's base type. FALSE is returned on error.

Esempi

Esempio 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); ?>
Il precedente esempio visualizzerà:
Title field type OID: 1043

Vedere anche:

pg_field_type()

pg_field_prtlen()

pg_field_name()

pg_field_type

(PHP 4 >= 4.2.0, PHP 5)

pg_field_type -- Restituisce il nome del tipo del campo specificato

Descrizione

string pg_field_type ( resource risultato, int numero_campo )

pg_field_type() restituisce una stringa contenente il nome del tipo del campo specificato da numero_campo nella risorsa PostgreSQL specificata da risultato. La numerazione dei campi comincia da 0.

Nota: Questa funzione si chiamava pg_fieldtype().

Vedere anche pg_field_prtlen() e pg_field_name().

pg_free_result

(PHP 4 >= 4.2.0, PHP 5)

pg_free_result -- Libera la memoria allocata per i risultati

Descrizione

bool pg_free_result ( resource risultato )

pg_free_result() deve essere chiamata solo se si è preoccupati di aver usato troppa memoria durante l'esecuzione dello script. Normalmente tutte le aree di memoria allocate per i risultati sono automaticamente deallocate alla fine dell'esecuzione. Se invece si è sicuri di non dover più utilizzare i dati del risultato, è possibile chiamare pg_free_result() con la risorsa result come argomento e la memoria associata verrà liberata. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Nota: Questa funzione si chiamava pg_freeresult().

pg_get_notify

(PHP 4 >= 4.3.0, PHP 5)

pg_get_notify -- Ping database connection

Description

array pg_get_notify ( resource connection [, int result_type] )

pg_get_notify() gets notify message sent by NOTIFY SQL command. To recieve nofigy messages, LISTEN SQL command must be issued. If there is notify message on the connection, array contains message name and backend PID is returned. If there is no message, FALSE is returned.

pg_get_pid

(PHP 4 >= 4.3.0, PHP 5)

pg_get_pid -- Ping database connection

Description

int pg_get_pid ( resource connection )

pg_get_pid() gets backend (database server process) PID. PID is useful to check if NOTIFY message is sent from other process or not.

pg_get_result

(PHP 4 >= 4.2.0, PHP 5)

pg_get_result -- Recupera i risultati di una query asincrona

Descrizione

resource pg_get_result ( [resource connessione] )

pg_get_result() estrae la risorsa risultato dalle query asincrone eseguite da pg_send_query(). pg_send_query() può inviare query multiple al server PostgreSQL server e pg_get_result() è utilizzat per recuperare i risultati uno ad uno. Restituisce la risorsa risultato. Se non ci sono più risultati, restituisce FALSE.

pg_host

(PHP 3, PHP 4, PHP 5)

pg_host -- Restituisce il nome dell'host associato alla connessione

Descrizione

string pg_host ( resource connessione )

pg_host() restituisce il nome dell'host a cui la risorsa PostgreSQL connessione è connessa.

Vedere anche pg_connect() e pg_pconnect().

pg_insert

(PHP 4 >= 4.3.0, PHP 5)

pg_insert -- Inserisce un array in una tabella.

Descrizione

bool pg_insert ( resource connessione, string nome_tabella, array array_assoc [, int opzioni] )

pg_insert() inserisce array_assoc composto da campo=>valore nella tabella specificata da nome_tabella. Se opzioni è specificato, pg_convert() è eseguita su array_assoc con le opzioni date.

Esempio 1. pg_insert

<?php 
    $db = pg_connect ('dbname=foo');
    // La riga seguente è sicura, dato che $_POST è convertito automaticamente
    $res = pg_insert($db, 'post_log', $_POST);
    if ($res) {
        echo "dati POST inseriti con successo\n";
    }
    else {
    echo "L'utente deve aver invitao dati sbagliati\n";
    }
?>

Nota: Questa funzione è sperimentale.

Vedere anche pg_convert()

pg_last_error

(PHP 4 >= 4.2.0, PHP 5)

pg_last_error -- Restituisce l'ultimo messaggio d'errore di una connessione

Descrizione

string pg_last_error ( [resource connessione] )

pg_last_error() restituisce l'ultimo messaggio di errore della connessione specificata.

I messaggi di errore possono essere sovrascritti da chiamate a funzioni interne a PostgreSQL(libpq). Quindi questa funzione potrebbe non restituire il messaggio di errore corretto, se più errori si sono verificati in una funzione interna di PostgreSQL.

Utilizzare pg_result_error(), pg_result_status() e pg_connection_status() per una migliore gestione degli errori.

Nota: Questa funzione si chiamava pg_errormessage().

Vedere anche pg_result_error().

pg_last_notice

(PHP 4 >= 4.0.6, PHP 5)

pg_last_notice -- Restituisce l'ultimo messaggio di notifica dal server PostgreSQL

Descrizione

string pg_last_notice ( resource connessione )

pg_last_notice() restituisce l'ultimo messaggio di notifica emesso dal server PostgreSQL specificato dal parametro connessione. Il server PostgreSQL invia messaggi di notifica in parecchi case, per esempio se le transazioni non possono essere continuate. Con pg_last_notice() è possibile evitare di eseguire query inutili, controllando se la notifica è relativa alla transazione o meno.

int pg_lo_create ( resource connessione )

pg_lo_create() crea un Large Object e restituisce l'oid dello stesso. connessione specifica una connessione valida al database aperta da pg_connect() o pg_pconnect(). I modi di accesso di PostgreSQL INV_READ, INV_WRITE e INV_ARCHIVE non sono supportati, l'oggetto è sempre creato con accesso sia in lettura che in scrittura. INV_ARCHIVE è stato rimosso da PostgreSQL (versioni 6.3 e successive). La funzione restituisce l'oid del large object, altrimenti restituisce FALSE in caso di errore.

Per utilizzare l'interfaccia large object (lo) è necessario includerla in un blocco di transazione.

Nota: Questa funzione si chiamava pg_locreate().

pg_lo_export

(PHP 4 >= 4.2.0, PHP 5)

pg_lo_export -- Esporta un large object salvandolo su un file

Descrizione

bool pg_lo_export ( int oid, string percorso [, resource connessione] )

L'argomento oid specifica l'oid del large object da salvare e l'argomento percorso specifica il percorso del file. Restituisce FALSE in caso di errore, TRUE altrimenti.

Per utilizzare l'interfaccia large object (lo), occorre includere il comando in un blocco di transazione.

Nota: Questa funzione si chiamava pg_loexport().

Vedere anche pg_lo_import().

pg_lo_import

(PHP 4 >= 4.2.0, PHP 5)

pg_lo_import -- Importa un large object da un file

Descrizione

int pg_lo_import ( [resource connessione, string percorso] )

Nelle versioni precedenti al PHP 4.2.0 la sintassi di questa funzione era differente, come nella seguente definizione:

int pg_lo_import ( string percorso [, resource connessione] )

Il parametro percorso specifica il percorso del file che deve essere importato nel large object. Restituisce FALSE in caso di errore, altrimenti l'oid del large object appena creato.

Per utilizzare l'interfaccia large object (lo), occorre includere il comando in un blocco di transazione.

Nota: Quando safe-mode è abilitato, PHP controlla che i file o le directory sulle quali si sta andando a lavorare, abbiano lo stesso UID dello script che è in esecuzione.

Nota: Questa fuinzione si chiamava pg_loimport().

Vedere anche pg_lo_export() e pg_lo_open().

pg_lo_open

(PHP 4 >= 4.2.0, PHP 5)

pg_lo_open -- Apre un large object

Descrizione

resource pg_lo_open ( resource connessione, int oid, string modo )

pg_lo_open() apre un Large Object e restituisce una risorsa (riferimento) large object. La risorsa incapsula le informazioni sulla connessione. oid specifica un oid valido di un large object e modo può essere "r", "w", o "rw". Restituisce FALSE se avviene un errore.

Avvertimento

Non chiudere la connessione al database prima di aver chiuso il large object.

Per utilizzare l'interfaccia large object (lo), occorre includere il comando in un blocco di transazione.

Nota: Questa funzione si chiamava pg_loopen().

Vedere anche pg_lo_close() e pg_lo_create().

pg_lo_read_all

(PHP 4 >= 4.2.0, PHP 5)

pg_lo_read_all -- Legge interamente un large object e lo manda direttamente al browser

Descrizione

int pg_lo_read_all ( resource large_object )

pg_lo_read_all() legge un large object e lo passa direttamente al browser dopo aver inviato tutti gli header in attesa. È pensata principalmente per inviare dati binari, come immagini o suoni. Restituisce il numero di byte letti. Restituisce FALSE in caso di errore.

Per utilizzare l'interfaccia large object (lo), occorre includere il comando in un blocco di transazione.

Nota: Questa funzione si chiamava pg_loreadall().

Vedere anche pg_lo_read().

pg_lo_read

(PHP 4 >= 4.2.0, PHP 5)

pg_lo_read -- Legge un large object

Descrizione

string pg_lo_read ( resource large_object, int lung )

pg_lo_read() legge al massimo lung byte da un large object e li restituisce sotto forma di stringa. large_object specifica una risorsa large object valida e lung specifica la lunghezza massima accettabile del segmento del large object. Restituisce FALSE in caso di errore.

Per utilizzare l'interfaccia large object (lo), occorre includere il comando in un blocco di transazione.

Nota: Questa funzione si chiamava pg_loread().

Per utilizzare l'interfaccia large object (lo), occorre includere il comando in un blocco di transazione.

Nota: Questa funzione si chiamava pg_lo_unlink().

Vedere anche pg_lo_create() e pg_lo_import().

pg_lo_write

(PHP 4 >= 4.2.0, PHP 5)

pg_lo_write -- Scrive un large object

Descrizione

int pg_lo_write ( resource large_object, string dati )

pg_lo_write() scrive su un large object i dati della variabile dati e restituisce il numero di byte scritti, oppure FALSE in caso di errore. large_object è una risorsa large object ottenuta attraverso pg_lo_open().

Per utilizzare l'interfaccia large object (lo), occorre includere il comando in un blocco di transazione.

Nota: Questa funzione si chiamava pg_lo_write().

Vedere anche pg_lo_create() e pg_lo_open().

pg_meta_data

(PHP 4 >= 4.3.0, PHP 5)

pg_meta_data -- Ottiene la definizione di una tabella.

Descrizione

array pg_meta_data ( resource connessione, string nome_tabella )

pg_metadata() resituisce la definizione della tabella nome_tabella sotto forma di array. Se avviane un errore, restituisce FALSE

Nota: Questa funzione è sperimentale.

Vedere anche pg_convert()

pg_num_fields

(PHP 4 >= 4.2.0, PHP 5)

pg_num_fields -- Restituisce il numero di campi

Descrizione

int pg_num_fields ( resource risultato )

pg_num_fields() restituisce il numero di campi (colonne) in un risultato PostgreSQL. L'argomento è una risorsa risultato ottenuta mediante pg_query(). Restituisce -1 in caso di errore.

Nota: Questa funzione si chiamava pg_numfields().

Vedere anche pg_num_rows() e pg_affected_rows().

pg_num_rows

(PHP 4 >= 4.2.0, PHP 5)

pg_num_rows -- Restituiscein numero di tuple

Descrizione

int pg_num_rows ( resource risultato )

pg_num_rows() restituisce il numero di tuple (righe) in un risultato PostgreSQL. risultato è una risorsa risultato ottenuta attraverso pg_query(). Restituisce -1 in caso di errore.

Nota: Utilizzare pg_affected_rows() per ottenere il numero di righe modificate da query INSERT, UPDATE and DELETE.

Nota: Questa funzione si chiamava pg_numrows().

Vedere anche pg_num_fields() e pg_affected_rows().

pg_options

(PHP 3, PHP 4, PHP 5)

pg_options -- Estrae le opzioni associate alla connessione

Descrizione

string pg_options ( resource connessione )

pg_options() restituisce una stringa contenente le opzioni specificate alla risorsa PostgreSQL connessione.

pg_parameter_status

(PHP 5)

pg_parameter_status -- Looks up a current parameter setting of the server.

Descrizione

string pg_parameter_status ( resource connection, string param_name )

string pg_parameter_status ( 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.

Attenzione

On a pre-7.4 PostgreSQL server, changing client_encoding via SET after connection startup will not be reflected by pg_parameter_status().

Elenco dei parametri

connection: PostgreSQL database connection resource. When connection is 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_name values include server_version, server_encoding, client_encoding, is_superuser, session_authorization, DateStyle, TimeZone, and integer_datetimes.

Valori restituiti

A string containing the value of the parameter, FALSE on failure or invalid param_name.

Esempi

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.

Elenco dei parametri

connection: PostgreSQL database connection resource. When connection is 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 parameterised 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.

Valori restituiti

A query result resource on success, or FALSE on failure.

Esempi

Esempio 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")); ?>

Vedere anche:

pg_execute()

pg_send_execute()

pg_put_line

(PHP 4 >= 4.0.3, PHP 5)

pg_put_line -- Invia una stringa terminata da NULL al backend PostgreSQL

Descrizione

bool pg_put_line ( [resource connessione, string dati] )

pg_put_line() invia una stringa terminata da NULL al backend PostgreSQL. Ciò è utile, per esempio, per l'inserimento ad alta velocità di dati in una tabella, iniziato mediante l'invocazione di una operazione di copia. Il carattere NULL finale è aggiunto automaticamente. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Nota: L'applicazione deve explicitamente inviare i due caratteri "\." sull'ultima riga, ad indicare al backend il termine dell'invio dei dati.

Vedere anche pg_end_copy().
Esempio 1. Inserimento ad alta velocità dai dati in una tabella
<?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.0RC1)

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.

Descrizione

resource pg_query_params ( resource connection, string query, array params )

resource pg_query_params ( 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.)

Elenco dei parametri

connection: PostgreSQL database connection resource. When connection is not present, the default connection is used. The default connection is the last connection made by pg_connect() or pg_pconnect().
query: The parameterised 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.

Valori restituiti

A query result resource on success, or FALSE on failure.

Esempi

Esempio 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}'"); ?>

Vedere anche:

pg_query()

pg_query

(PHP 4 >= 4.2.0, PHP 5)

pg_query -- Esegue una query

Descrizione

resource pg_query ( resource connessione, string query )

pg_query() restituisce un risorsa risultato della query se è stato possibile eseguire quest'ultima. Retituisce FALSE in caso di errore o se la connessione non è valida. I dettagli dell'errore si possono recuperare utilizzando la funzione pg_last_error() se la connessione è valida. pg_last_error() invia un comando SQL al database PostgreSQL specificato dalla risorsa connessione. Il parametro connessione deve essere una connessione valida restituita da pg_connect() o pg_pconnect(). Il valore di ritorno di questa funzione è una risorsa risultato che si può usare per accedere ai dati attraverso altre funzioni PostgreSQL come pg_fetch_array().

Nota: connessione è un parametro opzionale di pg_query(). Se connessione non è impostato, viene utilizzata la connessione di default, ovvero l'ultima connessione effettuata con pg_connect() o pg_pconnect().
Anche se connessione può essere omessa, ciò non è raccomandato, dal momento che questo può essere fonte di errori difficili da trovare nello script.

Nota: Questa funzione si chiamava pg_exec(). pg_exec() è ancora disponibile, per ragioni di compatibilità, ma si consiglia agli utenti di usare il nuovo nome.

Vedere anche pg_connect(), pg_pconnect(), pg_fetch_array(), pg_fetch_object(), pg_num_rows() e pg_affected_rows().

pg_result_error_field

(PHP 5 >= 5.1.0RC1)

pg_result_error_field -- Returns an individual field of an error report.

Descrizione

string pg_result_error_field ( resource 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.

Elenco dei parametri

result: A PostgreSQL query result resource from a previously executed statement.
fieldcode: Possible fieldcode values 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_LINE or PGSQL_DIAG_SOURCE_FUNCTION.

Valori restituiti

A string containing the contents of the error field, NULL if the field does not exist or FALSE on failure.

Esempi

Esempio 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); ?>

Vedere anche:

pg_result_error()

pg_result_error

(PHP 4 >= 4.2.0, PHP 5)

pg_result_error -- Restituisce i messaggio di errore associato al risultato

Descrizione

string pg_result_error ( resource risultato )

pg_result_error() restituisce il messaggio di errore associato alla risorsa risultato. Quindi, l'utente ha la possibilità di ottenere un messaggio più preciso rispetto alla pg_last_error().

vedere anche pg_query(), pg_send_query(), pg_get_result(), pg_last_error() e pg_last_notice()

pg_result_seek

(PHP 4 >= 4.3.0, PHP 5)

pg_result_seek -- Set internal row offset in result resource

Description

array pg_result_seek ( resource result, int offset )

pg_result_seek() set internal row offset in reuslt resource. It returns FALSE, if there is error.

pg_result_status

(PHP 4 >= 4.2.0, PHP 5)

pg_result_status -- Recupera lo stato del risultato di una query

Descrizione

int pg_result_status ( resource risultato )

pg_result_status() restituisce lo stato di una risorsa risultato. I valori di ritorno posso essere PGSQL_EMPTY_QUERY, PGSQL_COMMAND_OK, PGSQL_TUPLES_OK, PGSQL_COPY_TO, PGSQL_COPY_FROM, PGSQL_BAD_RESPONSE, PGSQL_NONFATAL_ERROR e PGSQL_FATAL_ERROR.

Vedere anche pg_connection_status().

pg_select

(PHP 4 >= 4.3.0, PHP 5)

pg_select -- Seleziona delle tuple.

Descrizione

array pg_select ( resource connessione, string nome_tabella, array array_assoc [, int opzioni] )

pg_select() seleziona le tuple specificate da array_assoc che ha la forma campo=>valore. Se la query ha successo, restituisce un array contenente tutte le tuple e i campi che corrispondono alla condizione specificata da array_assoc. Se opzioni è specificato, pg_convert() viene applicata ad array_assoc con le opzioni date.

Esempio 1. pg_select

<?php 
    $db = pg_connect ('dbname=foo');
    // La riga seguente è sicura, dal momento che $_POST viene convertita automaticamente
    $rec = pg_select($db, 'post_log', $_POST);
    if ($rec) {
        echo "Record selezionati\n";
        var_dump($rec);
    }
    else {
        echo "L'utente ha inviato dati errati\n";
    }
?>

Nota: Questa funzione è sperimentale.

Vedere anche pg_convert()

pg_send_execute

(PHP 5 >= 5.1.0RC1)

pg_send_execute -- Sends a request to execute a prepared statement with given parameters, without waiting for the result(s).

Descrizione

bool pg_send_execute ( resource 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.

Elenco dei parametri

connection: PostgreSQL database connection resource. When connection is 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.

Valori restituiti

Returns TRUE on success, FALSE on failure. Use pg_get_result() to determine the query result.

Esempi

Esempio 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); } ?>

Vedere anche:

pg_prepare()

pg_send_prepare()

pg_execute()

pg_send_prepare

(PHP 5 >= 5.1.0RC1)

pg_send_prepare -- Sends a request to create a prepared statement with the given parameters, without waiting for completion.

Descrizione

bool pg_send_prepare ( resource 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.

Elenco dei parametri

connection: PostgreSQL database connection resource. When connection is 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 parameterised 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.

Valori restituiti

Returns TRUE on success, FALSE on failure. Use pg_get_result() to determine the query result.

Esempi

Esempio 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); } ?>

Vedere anche:

pg_connect()

pg_pconnect()

pg_execute()

pg_send_execute()

pg_send_query_params()

pg_send_query_params

(PHP 5 >= 5.1.0RC1)

pg_send_query_params -- Submits a command and separate parameters to the server without waiting for the result(s).

Descrizione

bool pg_send_query_params ( resource 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.

Elenco dei parametri

connection: PostgreSQL database connection resource.
query: The parameterised 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.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Use pg_get_result() to determine the query result.

Esempi

Esempio 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}'"); ?>

Vedere anche:

pg_send_query()

pg_send_query

(PHP 4 >= 4.2.0, PHP 5)

pg_send_query -- Invia una query in modo asincrono

Descrizione

bool pg_send_query ( resource connessione, string query )

bool pg_send_query ( string query )

pg_send_query() manda in modo asincrono una query sulla connessione. Diversamente da pg_query(), può inviare più query a PostgreSQL e recuperare i risultati uno ad uno utilizzando pg_get_result(). L'esecuzione dello script non viene interrotta mentre le query sono in esecuzione. Utilizzare pg_connection_busy() per controllare se la connessione è occupata (es. una query è in esecuzione). Le query possono essere cancellate mediante pg_cancel_query().

Anche se è possibile inviare query multiple in un sol colpo, non è possibile inviare query multiple su una connessione occupata. Se la query è inviata mentre la connessione è occupata, la funzione aspetta la fine del processamento di tutti le query in coda, quindi scarta tutti i risultati.

Vedere anche pg_query(), pg_cancel_query(), pg_get_result() e pg_connection_busy()

pg_set_client_encoding

(PHP 3 CVS only, PHP 4 >= 4.0.3, PHP 5)

pg_set_client_encoding -- Imposta la codifica del client

Descrizione

int pg_set_client_encoding ( [resource connessione, string codifica] )

pg_set_client_encoding() imposta la codifica del client e restituisce 0 in caso di successo, -1 in caso di errore.

codifica è la codifica del client e può essere: SQL_ASCII, EUC_JP, EUC_CN, EUC_KR, EUC_TW, UNICODE, MULE_INTERNAL, LATINX (X=1...9), KOI8, WIN, ALT, SJIS, BIG5, WIN1250. Le codifiche disponibili dipendono dalle versionidi PostgreSQL e di libpq. Consultare il manuale di PostgreSQL per conoscere le cidifiche accettate dala propria installazione di PostgreSQL.

Nota: Questa funzione richiede PHP-4.0.3 o successiv e PostgreSQL-7.0 o successivi. Le codifiche accettate dipendono dalla versione di PostgreSQL. Consultare il manuale di PostgreSQL per ulteriori dettagli.
Questa funzione si chiamava pg_setclientencoding().

Vedere anche pg_client_encoding().

pg_set_error_verbosity

(PHP 5 >= 5.1.0RC1)

pg_set_error_verbosity -- Determines the verbosity of messages returned by pg_last_error() and pg_result_error().

Descrizione

int pg_set_error_verbosity ( resource connection, int verbosity )

int pg_set_error_verbosity ( 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.

Elenco dei parametri

connection: PostgreSQL database connection resource. When connection is 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_DEFAULT or PGSQL_ERRORS_VERBOSE.

Valori restituiti

The previous verbosity level: PGSQL_ERRORS_TERSE, PGSQL_ERRORS_DEFAULT or PGSQL_ERRORS_VERBOSE.

Esempi

Esempio 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); ?>

Vedere anche:

pg_last_error()

pg_result_error()

pg_trace

(PHP 4 >= 4.0.1, PHP 5)

pg_trace -- iAbilita il tracciamento di una connessione PostgreSQL

Descrizione

bool pg_trace ( string percorsofile [, string modo [, resource connessione]] )

pg_trace() abilita il tracciamento di una comunicazione frontend/backend PostgreSQL verso un file di debug specificato da percorsofile. Per riuscire a capire i risultati, occorre conoscere bene i dettagli del protocollo di comunicazione di PostgreSQL. Per chi non ne è a conoscenza, può sempre essere utile per tracciare gli errori nelle query mandate al server; ad esempio si può eseguire grep '^To backend' trace.log e vedere quale query è stata realmente inviata al server PostgreSQL. Per ulteriori informazioni, consultare il manuale di PostgreSQL.

percorsofile e modo sono gli stessi parametri di fopen() (mode ha come default 'w'), connession specifica la connessione da tracciare ed ha come default l'ultima aperta.

pg_trace() rRestituisce TRUE se percorsofile è stato apertoo in scrittura per il log, altrimenti FALSE.

Vedere anche:

fopen()

pg_untrace()

pg_transaction_status

(PHP 5 >= 5.1.0RC1)

pg_transaction_status -- Returns the current in-transaction status of the server.

Descrizione

int pg_transaction_status ( resource connection )

Returns the current in-transaction status of the server.

Attenzione

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.

Elenco dei parametri

connection: PostgreSQL database connection resource.

Valori restituiti

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.

Esempi

Esempio 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 3, PHP 4, PHP 5)

pg_tty -- Restituisce il nome della tty associata alla connessione

Descrizione

string pg_tty ( resource connessione )

pg_tty() restituisce il noe della tty a cui viene mandato l'output del debug del server sulla risorsa connessione specificata.

pg_unescape_bytea

(PHP 4 >= 4.3.0, PHP 5)

pg_unescape_bytea -- Escape binary for bytea type

Description

string pg_unescape_bytea ( string data )

pg_unescape_bytea() unescapes string from bytea datatype. It returns unescaped string (binary).

Nota: When you SELECT bytea type, PostgreSQL returns octal byte value prefixed by \ (e.g. \032). Users are supposed to convert back to binary format by yourself.
This function requires PostgreSQL 7.2 or later. With PostgreSQL 7.2.0 and 7.2.1, bytea type must be casted 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 cast. Exception is when client and backend character encoding does not match, there may be multi-byte stream error. User must cast to bytea to avoid this error.

pg_untrace

(PHP 4 >= 4.0.1, PHP 5)

pg_untrace -- Disabilita il tracciamento di una connessione PostgreSQL

Descrizione

bool pg_untrace ( [resource connessione] )

Termina il tracciamento cominciato con pg_trace(). connessione specifica la connessione tracciata ed ha come default l'ultima connessione aperta.

Restituisce sempre TRUE.

Vedere anche pg_trace().

pg_update

(PHP 4 >= 4.3.0, PHP 5)

pg_update -- Modifica le tuple della tabella

Descrizione

mixed pg_update ( resource connessione, string nome_tabella, array dati, array condizione [, int opzioni] )

pg_update() aggiorna le tuple che corrispondono a condizione con dati. Se opzioni è specificato, pg_convert() viene applicata su dati con le opzioni date.

Esempio 1. pg_update

<?php 
    $db = pg_connect ('dbname=foo');
    $data = array('field1'=>'AA', 'field2'=>'BB');
    // La riga seguente è sicura, date che $_POST è convertito automaticamente
    $res = pg_update($db, 'post_log', $_POST, $data);
    if ($res) {
        echo "Dati aggiornati: $res\n";
    }
    else {
        echo "L'utente ha inviato dati errati\n";
    }
?>

Nota: Questa funzione è sperimentale.

Vedere anche pg_convert()

pg_version

(PHP 5)

pg_version -- Returns an array with client, protocol and server version (when available)

Descrizione

array pg_version ( [resource connection] )

pg_version() returns an array with the client, protocol and server version. Protocol and server versions are only avaliable if PHP was compiled with PostgreSQL 7.4 or later.

For more detailed server information, use pg_parameter_status().

Elenco dei parametri

connection: PostgreSQL database connection resource. When connection is not present, the default connection is used. The default connection is the last connection made by pg_connect() or pg_pconnect().

Valori restituiti

Returns an array with client, protocol and server_version keys and values (if available). Returns FALSE on error or invalid connection.

Esempi

Esempio 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']; ?>
Il precedente esempio visualizzerà:
7.4

Vedere anche:

pg_parameter_status()

CXV. PostgreSQL Functions (PDO_PGSQL)

Introduzione

PDO_PGSQL is a driver that implements the PHP Data Objects (PDO) interface to enable access from PHP to PostgreSQL databases.

Sommario
PDO_PGSQL DSN -- Connecting to PostgreSQL databases

PDO_PGSQL DSN

(no version information, might be only in CVS)

PDO_PGSQL DSN -- Connecting to PostgreSQL databases

Descrizione

The PDO_PGSQL Data Source Name (DSN) is composed of the following elements, delimited by spaces:

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.

Esempi

Esempio 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

CXVI. Funzioni per le Stampanti

Introduzione

Queste funzioni sono disponibili solo nei sistemi Windows 9.x, ME, NT4 e 2000. Sono state aggiunte in PHP 4.0.4.

Installazione

Questo modulo PECL non viene incluso nel rilascio di PHP.

Per potere utilizzare queste funzioni, gli utenti Windows dovranno abilitare php_printer.dll nel php.ini. You may obtain this unbundled PECL extension from the various PECL snaps pages (select the appropriate repository for your version of PHP): PECL for PHP 4.3.x, PECL for PHP 5.0.x or PECL Unstable.

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

Tabella 1. Parametri di configurazione per il modulo stampante

Nome	Default	Modificabile	Variazioni
printer.default_printer	""	PHP_INI_ALL

Per maggiori dettagli sulle costanti PHP_INI_* vedere Appendice G.

Sommario
printer_abort -- Cancella il file di spool dalla stampante
printer_close -- Chiude una connessione aperta verso una stampante
printer_create_brush -- Crea un nuovo pennello
printer_create_dc -- Crea un nuovo device context
printer_create_font -- Crea un nuovo font
printer_create_pen -- Crea una nuova penna
printer_delete_brush -- Cancella un pennello
printer_delete_dc -- Cancella un device context
printer_delete_font -- Cancella un font
printer_delete_pen -- Cancella una penna
printer_draw_bmp -- Disegna una bitmap
printer_draw_chord -- Traccia una corda
printer_draw_elipse -- Traccia una ellisse
printer_draw_line -- Traccia una linea
printer_draw_pie -- Traccia una grafico a torta
printer_draw_rectangle -- Traccia un rettangolo
printer_draw_roundrect -- Traccia un rettangolo con gli angoli arrotondati
printer_draw_text -- Scrive un testo
printer_end_doc -- Chiude il documento
printer_end_page -- Chiude la pagina attiva
printer_get_option -- Recupera la configurazione della stampante
printer_list -- Restituisce un elenco delle stampanti collegate al server
printer_logical_fontheight -- Restituisce l'altezza logica del font
printer_open -- Apre la connessione ad una stampante
printer_select_brush -- Seleziona un pennello
printer_select_font -- Seleziona un font
printer_select_pen -- Seleziona una penna
printer_set_option -- Configura la connessione con la stampante
printer_start_doc -- Inizia un nuovo documento
printer_start_page -- Inizia una nuova pagina
printer_write -- Scrive dei dati sulla stampante

printer_abort

(PECL)

printer_abort -- Cancella il file di spool dalla stampante

Descrizione

void printer_abort ( resource handle )

La funzione cancella lo spool di stampa dalla stampante.

Il parametro handle deve indicare un handle valido di stampante.

Esempio 1. Esempio di utilizzo di printer_abort()

<?php
$handle = printer_open();
printer_abort($handle);
printer_close($handle);
?>

printer_close

(PECL)

printer_close -- Chiude una connessione aperta verso una stampante

Descrizione

void printer_close ( resource handle )

Questa funzione chiude la connessione verso una stampante. Inoltre, la funzione printer_close() chiude il device context attivo.

Il parametro handle deve indicare un handle valido di stampante.

Esempio 1. Esempio di utilizzo di printer_close()

<?php
$handle = printer_open();
printer_close($handle);
?>

printer_create_brush

(PECL)

printer_create_brush -- Crea un nuovo pennello

Descrizione

mixed printer_create_brush ( int stile, string colore )

La funzione crea un nuovo pennello e restituisce un handle per questo. Il pennello viene usato per riempire le forme. Per un esempio vedere printer_select_brush(). Il parametro colore deve essere un colore in formato esadecimale RGB, ad esempio "000000" per il nero, stile, invece, deve essere valorizzato con una delle seguenti costanti:

PRINTER_BRUSH_SOLID: crea un pennello con un colore pieno.
PRINTER_BRUSH_DIAGONAL: crea un pennello con righe a 45 gradi dal basso a sinistra verso l'alto a destra ( / ).
PRINTER_BRUSH_CROSS: crea un pennello con delle croci ( + ).
PRINTER_BRUSH_DIAGCROSS: crea un pennello con croci a 45 gradi ( x ).
PRINTER_BRUSH_FDIAGONAL: crea un pennello con righe a 45 gradi dall'alto a sinistra verso il basso a destra ( \ ).
PRINTER_BRUSH_HORIZONTAL: crea un pennello a righe orizzontali ( - ).
PRINTER_BRUSH_VERTICAL: crea un pennello a righe verticali ( | ).
PRINTER_BRUSH_CUSTOM: crea un pennello personalizzato a partire da un file BMP. Il secondo parametro viene usato per indicare il file BMP anzichè il codice RGB del colore.

printer_create_dc

(PECL)

printer_create_dc -- Crea un nuovo device context

Descrizione

void printer_create_dc ( resource handle )

La funzione crea un nuovo device context. Il device context è utilizzato per personalizzare gli oggetti grafici del documento. Il parametro handle deve indicare un handle valido di stampante.

Esempio 1. Esempio di utilizzo di printer_create_dc()

<?php
$handle = printer_open();
printer_start_doc($handle);
printer_start_page($handle);

printer_create_dc($handle);
/* esegue qualche operazione sul device context */
printer_set_option($handle, PRINTER_TEXT_COLOR, "333333");
printer_draw_text($handle, 1, 1, "text");
printer_delete_dc($handle);

/* crea un'altro device context */
printer_create_dc($handle);
printer_set_option($handle, PRINTER_TEXT_COLOR, "000000");
printer_draw_text($handle, 1, 1, "text");
/* ci esegue delle operazioni */

printer_delete_dc($handle);

printer_end_page($handle);
printer_end_doc($handle);
printer_close($handle);
?>

printer_create_font

(PECL)

printer_create_font -- Crea un nuovo font

Descrizione

mixed printer_create_font ( string tipo, int altezza, int larghezza, int spessore, bool corsivo, bool sottolineato, bool barrato, int orientamento )

La funzione crea un nuovo font e restituisce il relativo handle. Il font è utilizzato per scrivere testi. Per un esempio vedere printer_select_font(). Il parametro tipo è una stringa indicante il tipo di font. Altezza indica l'altezza del font e larghezza ne indica la larghezza. Il parametro spessore indica lo spessore del font (il valore normale è 400), e può essere una delle seguente costanti predefinite:

PRINTER_FW_THIN: imposta un font sottile (100).
PRINTER_FW_ULTRALIGHT: imposta un font molto leggero (200).
PRINTER_FW_LIGHT: imposta un font leggero (300).
PRINTER_FW_NORMAL: imposta un font normale (400).
PRINTER_FW_MEDIUM: imposta un font medio (500).
PRINTER_FW_BOLD: imposta il font a grassetto (700).
PRINTER_FW_ULTRABOLD: imposta il font ad un grassetto maggiore (800).
PRINTER_FW_HEAVY: imposta un font grosso (900).

Il parametro corsivo può essere TRUE o FALSE, ed indica se il font debba essere corsivo.

Il parametro sottolineato può essere TRUE o FALSE, e indica se il font debba essere sottolineato.

Il parametro barrato può essere TRUE o FALSE, e indica se il font debba essere barrato.

Il parametro orientamento specifica la rotazione. Per un esempio vedere printer_select_font().

printer_create_pen

(PECL)

printer_create_pen -- Crea una nuova penna

Descrizione

mixed printer_create_pen ( int stile, int larghezza, string colore )

La funzione crea una nuova penna e restituisce il relativo handle. Una penna viene usata per tracciare linee e curve. Per un esempio vedere printer_select_pen(). Il parametro colore deve essere un colore in formato esadecimale RGB, ad esempio "000000" per nero, larghezza specifica la larghezza della penna, mentre stile deve essere una delle seguenti costanti:

PRINTER_PEN_SOLID: crea una penna continua.
PRINTER_PEN_DASH: crea una penna tratteggiata.
PRINTER_PEN_DOT: crea una penna a punti.
PRINTER_PEN_DASHDOT: crea una penna con tratto e punto.
PRINTER_PEN_DASHDOTDOT: crea una penna con tratto e due punti.
PRINTER_PEN_INVISIBLE: crea una penna invisibile.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempio 1. Esempio di utilizzo di printer_draw_bmp()

<?php
$handle = printer_open();
printer_start_doc($handle, "My Document");
printer_start_page($handle);

printer_draw_bmp($handle, "c:\\image.bmp", 1, 1);

printer_end_page($handle);
printer_end_doc($handle);
printer_close($handle);
?>

printer_draw_chord

(PECL)

printer_draw_chord -- Traccia una corda

Descrizione

void printer_draw_chord ( resource handle, int rec_x, int rec_y, int rec_x1, int rec_y1, int rad_x, int rad_y, int rad_x1, int rad_y1 )

La funzione disegna una corda. Il parametro handle deve esesre un handle valido di stampante.

rec_x indica la coordinata x dell'angolo in alto a sinistra del rettangolo perimetrale.

rec_y indica la coordinata y dell'angolo in alto a sinistra del rettangolo perimetrale.

rec_x1 indica la coordinata x dell'angolo in basso a destra del rettangolo perimetrale.

rec_y1 indica la coordinata y dell'angolo in basso a destra del rettangolo perimetrale.

rad_x indica la coordinata x del radiale indicante l'inizio della corda.

rad_y indica la coordinata y del radiale indicante l'inizio della corda.

rad_x1 indica la coordinata x del radiale indicante la fine della corda.

rad_y1 indica la coordinata y del radiale indicante la fine della corda.

Esempio 1. Esempio di utilizzo di printer_draw_chord()

<?php
$handle = printer_open();
printer_start_doc($handle, "My Document");
printer_start_page($handle);

$pen = printer_create_pen(PRINTER_PEN_SOLID, 2, "000000");
printer_select_pen($handle, $pen);

$brush = printer_create_brush(PRINTER_BRUSH_SOLID, "2222FF");
printer_select_brush($handle, $brush);

printer_draw_chord($handle, 1, 1, 500, 500, 1, 1, 500, 1);

printer_delete_brush($brush);
printer_delete_pen($pen);

printer_end_page($handle);
printer_end_doc($handle);
printer_close($handle);   
?>

printer_draw_elipse

(PECL)

printer_draw_elipse -- Traccia una ellisse

Descrizione

void printer_draw_elipse ( resource handle, int ul_x, int ul_y, int lr_x, int lr_y )

La funzione disegna una ellisse. Il parametro handle deve esesre un handle valido di stampante.

ul_x indica la coordinata x in alto a sinistra dell'ellisse.

ul_y indica la coordinata y in alto a sinistra dell'ellisse.

lr_x indica la coordinata x in basso a destra dell'ellisse.

lr_y indica la coordinata y in basso a destra dell'ellisse.

Esempio 1. Esempio di utilizzo di printer_draw_elipse()

<?php
$handle = printer_open();
printer_start_doc($handle, "My Document");
printer_start_page($handle);

$pen = printer_create_pen(PRINTER_PEN_SOLID, 2, "000000");
printer_select_pen($handle, $pen);

$brush = printer_create_brush(PRINTER_BRUSH_SOLID, "2222FF");
printer_select_brush($handle, $brush);

printer_draw_elipse($handle, 1, 1, 500, 500);

printer_delete_brush($brush);
printer_delete_pen($pen);

printer_end_page($handle);
printer_end_doc($handle);
printer_close($handle);   
?>

printer_draw_line

(PECL)

printer_draw_line -- Traccia una linea

Description

void printer_draw_line ( resource printer_handle, int from_x, int from_y, int to_x, int to_y )

Questa funzione disegna una linea dalla posizione from_x, from_y alla posizione to_x, to_y usando la penna selezionata. Il parametro handle deve essere un handle valido di stampante.

Esempio 1. Esempio di utilizzo di printer_draw_line()

<?php
$handle = printer_open();
printer_start_doc($handle, "My Document");
printer_start_page($handle);

$pen = printer_create_pen(PRINTER_PEN_SOLID, 30, "000000");
printer_select_pen($handle, $pen);

printer_draw_line($handle, 1, 10, 1000, 10);
printer_draw_line($handle, 1, 60, 500, 60);

printer_delete_pen($pen);

printer_end_page($handle);
printer_end_doc($handle);
printer_close($handle);
?>

printer_draw_pie

(PECL)

printer_draw_pie -- Traccia una grafico a torta

Descrizione

void printer_draw_pie ( resource handle, int rec_x, int rec_y, int rec_x1, int rec_y1, int rad1_x, int rad1_y, int rad2_x, int rad2_y )

La funzione traccia un grafico a torta. Il parametro handle deve indicare un handle valido di stampante.

rec_x indica la coordinata x dell'angolo in alto a sinistra del rettangolo perimetrale.

rec_y indica la coordinata y dell'angolo in alto a sinistra del rettangolo perimetrale.

rec_x1 indica la coordinata x dell'angolo in basso a destra del rettangolo perimetrale.

rec_y1 indica la coordinata y dell'angolo in basso a destra del rettangolo perimetrale.

rad1_x indica la coordinata x del punto finale del primo raggio.

rad1_y indica la coordinata y del punto finale del primo raggio.

rad2_x indica la coordinata x del punto finale del secondo raggio.

rad2_y indica la coordinata y del punto finale del secondo raggio.

Esempio 1. Esempio di utilizzo di printer_draw_pie()

<?php
$handle = printer_open();
printer_start_doc($handle, "My Document");
printer_start_page($handle);

$pen = printer_create_pen(PRINTER_PEN_SOLID, 2, "000000");
printer_select_pen($handle, $pen);

$brush = printer_create_brush(PRINTER_BRUSH_SOLID, "2222FF");
printer_select_brush($handle, $brush);

printer_draw_pie($handle, 1, 1, 500, 500, 1, 1, 500, 1);

printer_delete_brush($brush);
printer_delete_pen($pen);

printer_end_page($handle);
printer_end_doc($handle);
printer_close($handle); 
?>

printer_draw_rectangle

(PECL)

printer_draw_rectangle -- Traccia un rettangolo

Descrizione

void printer_draw_rectangle ( resource handle, int ul_x, int ul_y, int lr_x, int lr_y )

La funzione disegna un rettangolo.

Il parametro handle deve indicare un handle valido di stampante.

ul_x indica la coordinata x dell'angolo in alto a sinistra del rettangolo.

ul_y indica la coordinata y dell'angolo in alto a sinistra del rettangolo.

lr_x indica la coordinata x dell'angolo in basso a destra del rettangolo.

lr_y indica la coordinata y dell'angolo in basso a destra del rettangolo.

Esempio 1. Esempio di utilizzo di printer_draw_rectangle()

<?php
$handle = printer_open();
printer_start_doc($handle, "My Document");
printer_start_page($handle);

$pen = printer_create_pen(PRINTER_PEN_SOLID, 2, "000000");
printer_select_pen($handle, $pen);

$brush = printer_create_brush(PRINTER_BRUSH_SOLID, "2222FF");
printer_select_brush($handle, $brush);

printer_draw_rectangle($handle, 1, 1, 500, 500);

printer_delete_brush($brush);
printer_delete_pen($pen);

printer_end_page($handle);
printer_end_doc($handle);
printer_close($handle);
?>

printer_draw_roundrect

(PECL)

printer_draw_roundrect -- Traccia un rettangolo con gli angoli arrotondati

Descrizione

void printer_draw_roundrect ( resource handle, int ul_x, int ul_y, int lr_x, int lr_y, int width, int height )

La funzione traccia un rettangolo con gli angoli arrotondati.

Il parametro handle deve indicare un handle valido di stampante.

ul_x indica la coordinata x dell'angolo in alto a sinistra del rettangolo.

ul_y indica la coordinata y dell'angolo in alto a sinistra del rettangolo.

lr_x indica la coordinata x dell'angolo in basso a destra del rettangolo.

lr_y indica la coordinata y dell'angolo in basso a destra del rettangolo.

width indica la larghezza dell'ellisse.

height indica l'altezza dell'ellisse.

Esempio 1. Esempio di utilizzo di printer_draw_roundrect()

<?php
$handle = printer_open();
printer_start_doc($handle, "My Document");
printer_start_page($handle);

$pen = printer_create_pen(PRINTER_PEN_SOLID, 2, "000000");
printer_select_pen($handle, $pen);

$brush = printer_create_brush(PRINTER_BRUSH_SOLID, "2222FF");
printer_select_brush($handle, $brush);

printer_draw_roundrect($handle, 1, 1, 500, 500, 200, 200);

printer_delete_brush($brush);
printer_delete_pen($pen);

printer_end_page($handle);
printer_end_doc($handle);
printer_close($handle);
?>

printer_draw_text

(PECL)

printer_draw_text -- Scrive un testo

Descrizione

void printer_draw_text ( resource printer_handle, string testo, int x, int y )

La funzione scrive il testo alla posizione x, y utilizzando il font selezionato. Il parametro printer_handle deve indicare un handle valido di stampante.

Esempio 1. Esempio di utilizzo di printer_draw_text()

<?php
$handle = printer_open();
printer_start_doc($handle, "My Document");
printer_start_page($handle);
$font = printer_create_font("Arial", 72, 48, 400, false, false, false ,0);
printer_select_font($handle, $font);
printer_draw_text($handle, "test", 10, 10);
printer_delete_font($font);

printer_end_page($handle);
printer_end_doc($handle);
printer_close($handle);
?>

PRINTER_DEVICENAME restituisce il nome della device della stampante.
PRINTER_DRIVERVERSION restituisce la versione del driver della stampante.

Esempio 1. Esempio di utilizzo di printer_get_option()

<?php
$handle = printer_open();
echo printer_get_option($handle, PRINTER_DRIVERVERSION);
printer_close($handle);
?>

printer_list

(PECL)

printer_list -- Restituisce un elenco delle stampanti collegate al server

Descrizione

array printer_list ( int enumtype [, string nome [, int livello]] )

La funzione elenca le stampanti disponibili e le loro capacità. Il parametro livello indica il livello delle informazioni richieste. I livelli possono essere 1,2,4 o 5. Il parametro enumtype deve essere valorizzato con una delle seguenti costanti:

PRINTER_ENUM_LOCAL: elenca le stampanti installate localmente.
PRINTER_ENUM_NAME: elenca le stampanti installate su nome, che può indicare un server, un dominio, un printer server.
PRINTER_ENUM_SHARED: questo parametro non può essere utilizzato da solo, è necessario aggiungerlo in OR ad uno degli altri, ad esempio PRINTER_ENUM_LOCAL per rilevare le stampanti locali condivise.
PRINTER_ENUM_DEFAULT: (solo Win9.x) elenca la stampante di default.
PRINTER_ENUM_CONNECTIONS: (solo WinNT/2000) elenca le stampanti che l'utente può utilizzare.
PRINTER_ENUM_NETWORK: (solo WinNT/2000) elenca le stampanti presenti nel dominio del computer. Opzione valida solo se livello è valorizzato a 1.
PRINTER_ENUM_REMOTE: (solo WinNT/2000) elenca le stampanti di rete ed i printer server presenti nel dominio del computer. Opzione valida solo se livello è valorizzato a 1.

Esempio 1. Esempio di utilizzo di printer_list()

<?php
/* rileva le stampanti locali condivise */
var_dump(printer_list(PRINTER_ENUM_LOCAL | PRINTER_ENUM_SHARED) );
?>

printer_logical_fontheight

(PECL)

printer_logical_fontheight -- Restituisce l'altezza logica del font

Descrizione

int printer_logical_fontheight ( resource handle, int altezza )

La funzione calcola l'altezza logica del font per il parametro altezza. Il parametro handle deve indicare un handle valido di stampante.

Esempio 1. Esempio di utilizzo di printer_logical_fontheight()

<?php
$handle = printer_open();
echo printer_logical_fontheight($handle, 72);
printer_close($handle);
?>

printer_open

(PECL)

printer_open -- Apre la connessione ad una stampante

Descrizione

mixed printer_open ( [string NomePeriferica] )

Questa funzione tenta di aprire una connessione con la stampante NomePeriferica, e restituisce un handle se ha successo oppure FALSE se fallisce.

Se non vengono passati parametri, la funzione tenta di aprire una connessione con la stampante di default (se non viene specificata in php.ini come printer.default_printer, il PHP tenta di determinarla).

Inoltre printer_open() attiva un device context.

Esempio 1. Esempio di utilizzo di printer_open()

<?php
$handle = printer_open("HP Deskjet 930c");
$handle = printer_open();
?>

printer_select_brush

(PECL)

printer_select_brush -- Seleziona un pennello

Descrizione

void printer_select_brush ( resource printer_handle, resource brush_handle )

La funzione seleziona un pennello come oggetto attivo per il disegno nel device context corrente. Un pennello viene utilizzato per riempire le figure. Se si disegna un rettangolo il pennello viene utilizzato per disegnarne la forma, mentre si utilizza la penna per tracciarne i contorni. Se non si seleziona alcun pennello prima di disegnare delle figure, queste non saranno riempite. Il parametro printer_handle deve indicare un handle valido di stampante. Il parametro brush_handle deve indicare un handle valido di pennello.

Esempio 1. Esempio di utilizzo di printer_select_brush()

<?php
$handle = printer_open();
printer_start_doc($handle, "My Document");
printer_start_page($handle);

$pen = printer_create_pen(PRINTER_PEN_SOLID, 2, "000000");
printer_select_pen($handle, $pen);
$brush = printer_create_brush(PRINTER_BRUSH_CUSTOM, "c:\\brush.bmp");
printer_select_brush($handle, $brush);
printer_draw_rectangle($handle, 1, 1, 500, 500);
printer_delete_brush($brush);
$brush = printer_create_brush(PRINTER_BRUSH_SOLID, "000000");
printer_select_brush($handle, $brush);
printer_draw_rectangle($handle, 1, 501, 500, 1001);
printer_delete_brush($brush);
printer_delete_pen($pen);
printer_end_page($handle);
printer_end_doc($handle);
printer_close($handle);
?>

printer_select_font

(PECL)

printer_select_font -- Seleziona un font

Descrizione

void printer_select_font ( resource printer_handle, resource font_handle )

La funzione seleziona un font con cui scrivere testi. Il parametro printer_handle deve indicare un handle valido di stampante. Il parametro font_handle deve indicare un handle valido di font.

Esempio 1. Esempio di utilizzo di printer_select_font()

<?php
$handle = printer_open();
printer_start_doc($handle, "My Document");
printer_start_page($handle);

$font = printer_create_font("Arial", 148, 76, PRINTER_FW_MEDIUM, false, false, false, -50);
printer_select_font($handle, $font);
printer_draw_text($handle, "PHP is simply cool", 40, 40);
printer_delete_font($font);

printer_end_page($handle);
printer_end_doc($handle);
printer_close($handle);
?>

printer_select_pen

(PECL)

printer_select_pen -- Seleziona una penna

Descrizione

void printer_select_pen ( resource printer_handle, resource pen_handle )

La funzione seleziona una penna come oggetto attivo di disegno per il device context corrente. Si utilizza una per penna per tracciare linee e curve. Ad esempio se si deve tracciare un linea singola si usa una penna. Se si disegna un rettangolo, si utilizza la penna per tracciare i bordi, mentre con il pennello si riempie l'interno. Se non si seleziona una penna prima di tracciare delle figure, queste non avranno i bordi. Il parametro printer_handle deve indicare un handle valido di stampante. Il parametro pen_handle deve indicare un handle valido di penna.

Esempio 1. Esempio di utilizzo di printer_select_pen()

<?php
$handle = printer_open();
printer_start_doc($handle, "My Document");
printer_start_page($handle);

$pen = printer_create_pen(PRINTER_PEN_SOLID, 30, "2222FF");
printer_select_pen($handle, $pen);

printer_draw_line($handle, 1, 60, 500, 60);

printer_delete_pen($pen);

printer_end_page($handle);
printer_end_doc($handle);
printer_close($handle);
?>

printer_set_option

(PECL)

printer_set_option -- Configura la connessione con la stampante

Descrizione

bool printer_set_option ( resource handle, int opzione, mixed valore )

La funzione valorizza le seguenti opzioni per la connessione corrente. Il parametro handle deve indicare un handle valido di stampante. Per il parametro opzione si può utilizzare una delle seguenti costanti:

PRINTER_COPIES: indica quante copie si debbano stampare, valore deve essere un intero.
PRINTER_MODE: specifica il tipo di dati (text, raw or emf), valore deve essere una stringa.
PRINTER_TITLE: specifica il nome del documento, valore deve essere una stringa.
PRINTER_ORIENTATION: specifica l'orientamento del foglio, valore può essere o PRINTER_ORIENTATION_PORTRAIT o PRINTER_ORIENTATION_LANDSCAPE
PRINTER_RESOLUTION_Y: specifica la risoluzione y in DPI, valore deve essere un intero.
PRINTER_RESOLUTION_X: specifica la risoluzione x in DPI, valore deve essere un intero.
PRINTER_PAPER_FORMAT: specifica il formato predefinito della carta, impostare valore a PRINTER_FORMAT_CUSTOM se si vuole impostare un formato personalizzato con PRINTER_PAPER_WIDTH e PRINTER_PAPER_LENGTH. Il parametro valore può essere una delle seguenti costanti.
- PRINTER_FORMAT_CUSTOM: specifica un formato personalizzato.
- PRINTER_FORMAT_LETTER: specifica il formato letter (8 1/2- per 11-pollici).
- PRINTER_FORMAT_LETTER: specifica il formato legal (8 1/2- per 14-pollici).
- PRINTER_FORMAT_A3: specifica il formato A3 (297- per 420-millimetri).
- PRINTER_FORMAT_A4: specifica il formato A4 (210- per 297-millimetri).
- PRINTER_FORMAT_A5: specifica il formato A5 (148- per 210-millimetri).
- PRINTER_FORMAT_B4: specifica il formato B4 (250- per 354-millimetri).
- PRINTER_FORMAT_B5: specifica il formato B5 (182- per 257-millimetri).
- PRINTER_FORMAT_FOLIO: specifica il formato FOLIO (8 1/2- per 13-pollici).
PRINTER_PAPER_LENGTH: se PRINTER_PAPER_FORMAT è impostato a PRINTER_FORMAT_CUSTOM, PRINTER_PAPER_LENGTH specifica la lunghezza personalizzata in mm, valore deve essere un intero.
PRINTER_PAPER_WIDTH: se PRINTER_PAPER_FORMAT è impostato a PRINTER_FORMAT_CUSTOM, PRINTER_PAPER_WIDTH specifica la larghezza personalizzata in mm, valore deve essere un intero.
PRINTER_SCALE: specifica il fattore per il quale l'output della stampante deve essere dimensionato. La dimensione dalle pagine viene modificata dalla dimensione fisica di un fattore pari a scala/100. Ad esempio se simposta scala a 50, l'output sarà la metà della dimensione originale. Valore deve essere un intero.
PRINTER_BACKGROUND_COLOR: specifica il colore di background per il device context corrente, valore deve essere una stringa contenente il colore in formato RGB esadecimale, ad esempio "005533".
PRINTER_TEXT_COLOR: specifica il colore del testo per il device context corrente, valore deve essere una stringa contenente il colore in formato RGB esadecimale, ad esempio "005533".
PRINTER_TEXT_ALIGN: specifica l'allineamento del testo per il device context corrente, valore può essere la combinazione tramite OR delle seguenti costanti:
- PRINTER_TA_BASELINE: il testo sarà allineato alla linea base.
- PRINTER_TA_BOTTOM: il testo sarà allineato in basso.
- PRINTER_TA_TOP: il testo sarà allineato in alto.
- PRINTER_TA_CENTER: il testo sarà centrato.
- PRINTER_TA_LEFT: il testo sarà allineato a sinistra.
- PRINTER_TA_RIGHT: il testo sarà allineato a destra.

Esempio 1. Esempio di utilizzo di printer_set_option()

<?php
$handle = printer_open();
printer_set_option($handle, PRINTER_SCALE, 75);
printer_set_option($handle, PRINTER_TEXT_ALIGN, PRINTER_TA_LEFT);
printer_close($handle);
?>

printer_start_doc

(PECL)

printer_start_doc -- Inizia un nuovo documento

Descrizione

bool printer_start_doc ( resource handle [, string documento] )

La funzione crea un nuovo documento nello spooler della stampante. Il documento può contenere diverse pagine, la funzione è utilizzata per inserire un job di stampa nello spooler. Il parametro handle deve essere un handle valido di una stampante. Il parametro opzionale documento può esesre usato per indicare un nome alternativo al documento.

Esempio 1. Esempio di utilizzo di printer_start_doc()

<?php
$handle = printer_open();
printer_start_doc($handle, "My Document");
printer_start_page($handle);

printer_end_page($handle);
printer_end_doc($handle);
printer_close($handle);
?>

printer_start_page

(PECL)

printer_start_page -- Inizia una nuova pagina

Descrizione

bool printer_start_page ( resource handle )

La funzione crea una nuova pagina nel documento attivo. Per un esempio vedere printer_start_doc(). Il parametro handle deve essere un handle valido di stampante.

printer_write

(PECL)

printer_write -- Scrive dei dati sulla stampante

Descrizione

bool printer_write ( resource handle, string contenuto )

La funzione scrive contenuto direttamente alla stampante. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Il parametro handle deve essere un handle valido di una stampante.

Esempio 1. Esempio di utilizzo di printer_write()

<?php
$handle = printer_open();
printer_write($handle, "Testo da scrivere");
printer_close($handle);
?>

CXVII. Funzioni per l'esecuzione di programmi

Introduzione

Queste funzioni permettono l'esecuzione di comandi sul sistema stesso, e rendono sicuri tali comandi.

Requisiti

Non sono necessarie librerie esterne per utilizzare questo modulo.

Installazione

Non è necessaria nessuna installazione per usare queste funzioni, esse fanno parte del core di PHP.

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

Questa estensione non definisce alcuna costante.

Vedere anche:

Queste funzioni sono anche strettamente correlate al operatore backtick. Inoltre, in modalità sicura occorre tenere conto anche della direttiva safe_mode_exec_dir.

Sommario
escapeshellarg -- estrae una stringa da usare come un argomento della shell
escapeshellcmd -- Elude i metacaratteri della shell
exec -- Esegue un programma esterno
passthru -- Esegue un programma esterno e mostra l'output non elaborato
proc_close -- Close a process opened by proc_open() and return the exit code of that process.
proc_get_status -- Get information about a process opened by proc_open()
proc_nice -- Change the priority of the current process
proc_open -- Execute a command and open file pointers for input/output
proc_terminate -- kills a process opened by proc_open
shell_exec -- Esegue un comando attraverso la shell e restituisce l'output completo come stringa
system -- Esegue un programma esterno e mostra l'output

escapeshellarg

(PHP 4 >= 4.0.3, PHP 5)

escapeshellarg -- estrae una stringa da usare come un argomento della shell

Descrizione

string escapeshellarg ( string arg )

escapeshellarg() aggiunge le virgolette singole attorno ad una stringa ed elude ogni virgoletta semplice per permetterti di passare una stringa direttamente ad una funzione della shell a che questa venga trattata come un singolo argomento. Questa funzione dovrebbe essere usata per eludere argomenti individuali per funzioni della shell che giungano dall'input del utente. Le funzioni della shell includono exec(), system() e l'operatore backtick. Un utilizzo standard sarebbe:

<?php
system('ls '.escapeshellarg($dir));

Vedere anche escapeshellcmd(), exec(), popen(), system() e l'operatore backtick.

escapeshellcmd

(PHP 3, PHP 4, PHP 5)

escapeshellcmd -- Elude i metacaratteri della shell

Descrizione

string escapeshellcmd ( string command )

escapeshellcmd() elude ogni carattere di una stringa che potrebbe essere usata per indurre un comando shell ad eseguire comandi arbitrari. Questa funzione dovrebbe essere usata per assicurarsi che ogni dato che giunga dall'input dell'utente venga neutralizzato prima di essere passato a funzioni come exec() o system() o all'operatore backtick . Un modello d'utilizzo potrebbe essere:

<?php
$e = escapeshellcmd($userinput);

// qui non ci preoccupiamo se $e contiene spazi
system("echo $e");
$f = escapeshellcmd($filename);
// e qui lo facciamo, usando le virgolette
system("touch \"/tmp/$f\"; ls -l \"/tmp/$f\""); 
?>

Vedere anche escapeshellarg(), exec(), popen(), system() e l'operatore backtick.

exec

(PHP 3, PHP 4, PHP 5)

exec -- Esegue un programma esterno

Descrizione

string exec ( string command [, array &output [, int &return_var]] )

exec() esegue il comando passato da command, la funzione non invia nessun output. Restituisce semplicemente l'ultima linea dal risultato del comando. Se si ha bisogno di eseguire un comando ed avere tutti i dati passati direttamente indietro senza alcuna interferenza, usare la funzione passthru().

Se l'argomento output è presente, allora tale vettore specificato verrà riempito con ogni linea del output del comando. I fine riga, come \nnon sono inclusi in questo array. Notare che se il vettore contiene già degli elementi, exec() li aggiungerà in coda al vettore. Se non si vuole che la funzione aggiunga elementi, eseguire un unset() sul vettore prima di passarlo ad exec().

Se viene passato l'argomento return_var assieme all'argomento output, allora lo stato del comando eseguito verrà scritto in questa variabile.

Esempio 1. Un exec() example
<?php // restituisce la username del proprietario del processo php/httpd attivo // (su um sistema con l'eseguibile "whoami" nel path) echo exec('whoami'); ?>

Avvertimento

Se si permette di passare a questa funzione i dati provenineti dagli input utente, si dovrebbe utilizzare la funzione escapeshellarg() oppure escapeshellcmd() in modo da essere sicuri che gli utenti non possano compromettere il sistema eseguendo comandi arbitrari.

Nota: Se si vuole avviare un programma tramite questa funzione e lasciarlo girare in background, occorre essere certi che l output del programma sia rediretto su un file o qualche altro flusso di output altrimenti il PHP sarà sospenderà fino a quando il programma non termina.

Nota: Quando si abilita la modalità sicura, si può eseguire soltanto gli eseguibili presenti nella directory safe_mode_exec_dir. Per motivi pratici, attualmente, non ` permesso avere .. come componente del percorso di un eseguibile.

Avvertimento

Con la modalità sicura attivata, tutte le parole che seguono il comando iniziale sono trattate come argomenti. Quindi, echo y | echo x diventa echo "y | echo x".

Vedere anche system(), passthru(), popen(), escapeshellcmd() pcntl_exec() e l'operatore backtick.

passthru

(PHP 3, PHP 4, PHP 5)

passthru -- Esegue un programma esterno e mostra l'output non elaborato

Descrizione

void passthru ( string command [, int &return_var] )

La funzione passthru() è simile alla funzione exec() inquanto esegue command. Se il parametro return_var è specificato, lo stato ritornato dal comando Unix verrà posto lì. Questa funzione deve essere usata al posto di exec() o di system() quando l'output del comando Unix consiste in dati binari da passare direttamente al browser. Un suo uso frequente consiste nel eseguire, ad esempio, le utility pbmplus che possono restituire un flusso diretto all'immagine. Impostado il tipo di contenuto a image/gif e successivamente chiamando un programma pbmplus per generare una gif puoi realizzare uno script PHP che genera direttamente immagini.

Avvertimento

Nota: Se si vuole avviare un programma tramite questa funzione e lasciarlo girare in background, occorre essere certi che l output del programma sia rediretto su un file o qualche altro flusso di output altrimenti il PHP sarà sospenderà fino a quando il programma non termina.

Nota: Quando si abilita la modalità sicura, si può eseguire soltanto gli eseguibili presenti nella directory safe_mode_exec_dir. Per motivi pratici, attualmente, non ` permesso avere .. come componente del percorso di un eseguibile.

Avvertimento

Con la modalità sicura attivata, tutte le parole che seguono il comando iniziale sono trattate come argomenti. Quindi, echo y | echo x diventa echo "y | echo x".

Vedere anche exec(), system(), popen(), escapeshellcmd(), e l'operatore backtick.

proc_close

(PHP 4 >= 4.3.0, PHP 5)

proc_close -- Close a process opened by proc_open() and return the exit code of that process.

Descrizione

int proc_close ( resource process )

proc_close() is similar to pclose() except that it only works on processes opened by proc_open(). proc_close() waits for the process to terminate, and returns its exit code. If you have open pipes to that process, you should fclose() them prior to calling this function in order to avoid a deadlock - the child process may not be able to exit while the pipes are open.

Elenco dei parametri

process: The proc_open() resource that will be closed.

proc_get_status

(PHP 5)

proc_get_status -- Get information about a process opened by proc_open()

Descrizione

array proc_get_status ( resource process )

proc_get_status() fetches data about a process opened using proc_open().

Elenco dei parametri

process: The proc_open() resource that will be evaluated.

Valori restituiti

An array of collected information on success, and FALSE on failure. The returned array contains the following elements:

element	type	description
command	string	The command string that was passed to proc_open()
pid	int	process id
running	bool	`TRUE` if the process is still running, `FALSE` if it has terminated
signaled	bool	`TRUE` if the child process has been terminated by an uncaught signal. Always set to `FALSE` on Windows.
stopped	bool	`TRUE` if the child process has been stopped by a signal. Always set to `FALSE` on Windows.
exitcode	int	the exit code returned by the process (which is only meaningful if `running` is `FALSE`)
termsig	int	the number of the signal that caused the child process to terminate its execution (only meaningful if `signaled` is `TRUE`)
stopsig	int	the number of the signal that caused the child process to stop its execution (only meaningful if `stopped` is `TRUE`)

Vedere anche:

proc_open()

proc_nice

(PHP 5)

proc_nice -- Change the priority of the current process

Descrizione

bool proc_nice ( int increment )

proc_nice() changes the priority of the current process by the amount specified in increment. A positive increment will lower the priority of the current process, whereas a negative increment will raise the priority.

proc_nice() is not related to proc_open() and its associated functions in any way.

Elenco dei parametri

increment: The increment value of the priority change.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento. If an error occurs, like the user lacks permission to change the priority, an error of level E_WARNING is also generated.

Note

Availability: proc_nice() will only exist if your system has 'nice' capabilities. 'nice' conforms to: SVr4, SVID EXT, AT&T, X/OPEN, BSD 4.3. This means that proc_nice() is not available on Windows.

proc_open

(PHP 4 >= 4.3.0, PHP 5)

proc_open -- Execute a command and open file pointers for input/output

Descrizione

resource proc_open ( string cmd, array descriptorspec, array &pipes [, string cwd [, array env [, array other_options]]] )

proc_open() is similar to popen() but provides a much greater degree of control over the program execution.

PHP 5 introduces pty support for systems with Unix98 ptys. This allows your script to interact with applications that expect to be talking to a terminal. A pty works like a pipe, but is bi-directional, so there is no need to specify a read/write mode. The example below shows how to use a pty; note that you don't have to have all descriptors talking to a pty. Also note that only one pty is created, even though pty is specified 3 times. In a future version of PHP, it might be possible to do more than just read and write to the pty.

Elenco dei parametri

cmd

The command to execute

descriptorspec

An indexed array where the key represents the descriptor number and the value represents how PHP will pass that descriptor to the child process. 0 is stdin, 1 is stdout, while 2 is stderr.

The currently supported pipe types are file, pipe and pty.

The file descriptor numbers are not limited to 0, 1 and 2 - you may specify any valid file descriptor number and it will be passed to the child process. This allows your script to interoperate with other scripts that run as "co-processes". In particular, this is useful for passing passphrases to programs like PGP, GPG and openssl in a more secure manner. It is also useful for reading status information provided by those programs on auxiliary file descriptors.

pipes

Will be set to an indexed array of file pointers that correspond to PHP's end of any pipes that are created.

cwd

The initial working dir for the command. This must be an absolute directory path, or NULL if you want to use the default value (the working dir of the current PHP process)

env

An array with the environment variables for the command that will be run, or NULL to use the same environment as the current PHP process

other_options

Allows you to specify additional options. Currently only suppress_errors is supported, which suppresses errors generated by this function when it's set to TRUE

Valori restituiti

Returns a resource representing the process, which should be freed using proc_close() when you are finished with it. On failure returns FALSE.

Log delle modifiche

Versione	Descrizione
5.0.0.	Added the `cwd`, `env` and `other_options` parameters. Added support for Unix98 ptys.

Esempi

Esempio 1. A proc_open() example
<?php $descriptorspec = array( 0 => array("pipe", "r"), // stdin is a pipe that the child will read from 1 => array("pipe", "w"), // stdout is a pipe that the child will write to 2 => array("file", "/tmp/error-output.txt", "a") // stderr is a file to write to ); $cwd = '/tmp'; $env = array('some_option' => 'aeiou'); $process = proc_open('php', $descriptorspec, $pipes, $cwd, $env); if (is_resource($process)) { // $pipes now looks like this: // 0 => writeable handle connected to child stdin // 1 => readable handle connected to child stdout // Any error output will be appended to /tmp/error-output.txt fwrite($pipes[0], '<?php print_r($_ENV); ?>'); fclose($pipes[0]); echo stream_get_contents($pipes[1]); fclose($pipes[1]); // It is important that you close any pipes before calling // proc_close in order to avoid a deadlock $return_value = proc_close($process); echo "command returned $return_value\n"; } ?>
Il precedente esempio visualizzerà qualcosa simile a:
Array ( [some_option] => aeiou [PWD] => /tmp [SHLVL] => 1 [_] => /usr/local/bin/php ) command returned 0

Esempio 2. ptys usage
<?php // Create a pseudo terminal for the child process $descriptorspec = array( 0 => array("pty"), 1 => array("pty"), 2 => array("pty") ); $process = proc_open("cvs -d:pserver:cvsread@cvs.php.net:/repository login", $descriptorspec, $pipes); if (is_resource($process)) { // work with it here } ?>

Note

Nota: Windows compatibility: Descriptors beyond 2 (stderr) are made available to the child process as inheritable handles, but since the Windows architecture does not associate file descriptor numbers with low-level handles, the child process does not (yet) have a means of accessing those handles. Stdin, stdout and stderr work as expected.

Nota: If you only need a uni-directional (one-way) process pipe, use popen() instead, as it is much easier to use.

Vedere anche:

popen()

exec()

system()

passthru()

stream_select()

The backtick operator

proc_terminate

(PHP 5)

proc_terminate -- kills a process opened by proc_open

Descrizione

int proc_terminate ( resource process [, int signal] )

Signals a process (created using proc_open()) that it should terminate. proc_terminate() returns immediately and does not wait for the process to terminate.

The optional signal is only useful on POSIX operating systems; you may specify a signal to send to the process using the kill(2) system call. The default is SIGTERM.

proc_terminate() allows you terminate the process and continue with other tasks. You may poll the process (to see if it has stopped yet) by using the proc_get_status() function.

Vedere anche:

proc_open()

proc_close()

proc_get_status()

shell_exec

(PHP 4, PHP 5)

shell_exec -- Esegue un comando attraverso la shell e restituisce l'output completo come stringa

Descrizione

string shell_exec ( string cmd )

Questa funzione è identica all'operatore backtick.

Esempio 1. Un shell_exec() esempio
<?php $output = shell_exec('ls -lart'); echo "<pre>$output</pre>"; ?>

Nota: Questa funzione è disabilitata nella modalitàsafe-mode

Vedere anche exec() e escapeshellcmd().

system

(PHP 3, PHP 4, PHP 5)

system -- Esegue un programma esterno e mostra l'output

Descrizione

string system ( string command [, int &return_var] )

system() è semplicemente come la versione C della funzione che esegue il command dato e restituisce in uscita il risultato. Se viene fornita una variabile come secondo argomento, allora il codice di stato ritornato dal comando eseguito verrà scritto in tale variabile.

Avvertimento

Nota: Se si vuole avviare un programma tramite questa funzione e lasciarlo girare in background, occorre essere certi che l output del programma sia rediretto su un file o qualche altro flusso di output altrimenti il PHP sarà sospenderà fino a quando il programma non termina.

La chiamata a system() tenta anche di ripulire automaticamente il buffer di output del web server dopo ogni linea di output se PHP gira come un modulo server.

Restituisce l'ultima linea del output del comando se ha successo e FALSE se fallisce.

Se devi eseguire un comando ottenendo tutti i dati restituiti dal comando direttamente senza alcuna interferenza, usa la funzione passthru().

Esempio 1. system() example
<?php echo '<pre>'; // Mette in output tutti i risultati della shellcommand "ls", e restituisce // l'ultima linea di output nella $last_line. Memorizza il valore restituito // del comando da shell in $retval. $last_line = system('ls', $retval); // Stampa informazioni aggiuntive echo ' </pre> <hr />L'ultima linea dell'output: ' . $last_line . ' <hr />Restituisce il valore: ' . $retval; ?>

Nota: Quando si abilita la modalità sicura, si può eseguire soltanto gli eseguibili presenti nella directory safe_mode_exec_dir. Per motivi pratici, attualmente, non ` permesso avere .. come componente del percorso di un eseguibile.

Avvertimento

Con la modalità sicura attivata, tutte le parole che seguono il comando iniziale sono trattate come argomenti. Quindi, echo y | echo x diventa echo "y | echo x".

Vedere anche exec(), passthru(), popen(), escapeshellcmd(), pcntl_exec(), e l'operatore backtick.

CXVIII. PostScript document creation

Introduzione

This module allows to create PostScript documents. It has many similarities with the pdf extension. Actually the API is almost identical and one can in many cases just replace the prefix of each function from pdf_ to ps_. This also works for functions which has no meaning in the PostScript document (like adding hyperlinks) but will have an effect if the document is converted to PDF.

Documents created by this extension are sometimes even superior to documents created with the pdf extension, because pslib's text rendering functions can handle kerning, hyphenation and ligatures which results in much better output of boxed text.

Requisiti

You need at least PHP 4.3.0 and pslib >= 0.1.12. The ps library (pslib) is available at http://pslib.sourceforge.net/.

Installazione

A short installation note: just type
$ pear install ps
in your console.

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

The following two tables lists all constants defined by the ps extension.

Tabella 1. Contants for line caps

Name	Meaning
ps_LINECAP_BUTT
ps_LINECAP_ROUND
ps_LINECAP_SQUARED

Tabella 2. Contants for line joins

Name	Meaning
ps_LINEJOIN_MITER
ps_LINEJOIN_ROUND
ps_LINEJOIN_BEVEL

Contact Information

If you have comments, bugfixes, enhancements for either this extension or pslib then please drop me a mail steinm@php.net. Any help is very welcome.

Sommario
ps_add_bookmark -- Add bookmark to current page
ps_add_launchlink -- Adds link which launches file
ps_add_locallink -- Adds link to a page in the same document
ps_add_note -- Adds note to current page
ps_add_pdflink -- Adds link to a page in a second pdf document
ps_add_weblink -- Adds link to a web location
ps_arc -- Draws an arc counterclockwise
ps_arcn -- Draws an arc clockwise
ps_begin_page -- Start a new page
ps_begin_pattern -- Start a new pattern
ps_begin_template -- Start a new template
ps_circle -- Draws a circle
ps_clip -- Clips drawing to current path
ps_close_image -- Closes image and frees memory
ps_close -- Closes a PostScript document
ps_closepath_stroke -- Closes and strokes path
ps_closepath -- Closes path
ps_continue_text -- Continue text in next line
ps_curveto -- Draws a curve
ps_delete -- Deletes all resources of a PostScript document
ps_end_page -- End a page
ps_end_pattern -- End a pattern
ps_end_template -- End a template
ps_fill_stroke -- Fills and strokes the current path
ps_fill -- Fills the current path
ps_findfont -- Loads a font
ps_get_buffer -- Fetches the full buffer containig the generated PS data
ps_get_parameter -- Gets certain parameters
ps_get_value -- Gets certain values
ps_hyphenate -- Hyphenates a word
ps_lineto -- Draws a line
ps_makespotcolor -- Create spot color
ps_moveto -- Sets current point
ps_new -- Creates a new PostScript document object
ps_open_file -- Opens a file for output
ps_open_image_file -- Opens image from file
ps_open_image -- Reads an image for later placement
ps_place_image -- Places image on the page
ps_rect -- Draws a rectangle
ps_restore -- Restore previously save context
ps_rotate -- Sets rotation factor
ps_save -- Save current context
ps_scale -- Sets scaling factor
ps_set_border_color -- Sets color of border for annotations
ps_set_border_dash -- Sets length of dashes for border of annotations
ps_set_border_style -- Sets border style of annotations
ps_set_info -- Sets information fields of document
ps_set_parameter -- Sets certain parameters
ps_set_text_pos -- Sets position for text output
ps_set_value -- Sets certain values
ps_setcolor -- Sets current color
ps_setdash -- Sets appearance of a dashed line
ps_setflat -- Sets flatness
ps_setfont -- Sets font to use for following output
ps_setgray -- Sets gray value
ps_setlinecap -- Sets appearance of line ends
ps_setlinejoin -- Sets how contected lines are joined
ps_setlinewidth -- Sets width of a line
ps_setmiterlimit -- Sets the miter limit
ps_setpolydash -- Sets appearance of a dashed line
ps_shading_pattern -- Creates a pattern based on a shading
ps_shading -- Creates a shading for later use
ps_shfill -- Fills an area with a shading
ps_show_boxed -- Output text in a box
ps_show_xy -- Output text at given position
ps_show -- Output text
ps_string_geometry -- Gets geometry of a string
ps_stringwidth -- Gets width of a string
ps_stroke -- Draws the current path
ps_symbol_name -- Gets name of a glyph
ps_symbol_width -- Gets width of a glyph
ps_symbol -- Output a glyph
ps_translate -- Sets translation

ps_add_bookmark

(PECL)

ps_add_bookmark -- Add bookmark to current page

Descrizione

int ps_add_bookmark ( resource psdoc, string text [, int parent [, int open]] )

Adds a bookmark for the current page. Bookmarks usually appear in PDF-Viewers left of the page in a hierarchical tree. Clicking on a bookmark will jump to the given page.

The bookmark has no meaning if the document is printed or viewed but it will be used if the document is converted to pdf by either Acrobat Distiller™ or Ghostview.

Elenco dei parametri

psdoc
text
parent: The parameter parent is another bookmark which is used as the parent of the new bookmark.
open: If open is unequal to zero the bookmark will be shown open by the pdf viewer.

Valori restituiti

The returned value is a reference for the bookmark. It is only used if the bookmark shall be used as a parent.

Returns the identifier of the bookmark or zero in case of an error. The identifier is a positive number.

Vedere anche:

ps_add_launchlink()

ps_add_launchlink

(PECL)

ps_add_launchlink -- Adds link which launches file

Descrizione

bool ps_add_launchlink ( resource psdoc, float llx, float lly, float urx, float ury, string filename )

Places a hyperlink at the given position pointing to a file program which is being started when clicked on. The hyperlink start is a rectangle with its lower left corner at (llx, lly) and its upper right corner at (urx, ury). The rectangle has by default a thin blue border.

The hyperlink will not be visible if the document is printed or viewed but it will show up if the document is converted to pdf by either Acrobat Distiller™ or Ghostview.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

ps_add_locallink()

ps_add_locallink

(PECL)

ps_add_locallink -- Adds link to a page in the same document

Descrizione

bool ps_add_locallink ( resource psdoc, float llx, float lly, float urx, float ury, int page, string dest )

Places a hyperlink at the given position pointing to a page in the same document. Clicking on the link will jump to the given page. The first page in a document has number 1.

The hyperlink start is a rectangle with its lower left corner at (llx, lly) and its upper right corner at (urx, ury). The rectangle has by default a thin blue border.

The hyperlink will not be visible if the document is printed or viewed but it will show up if the document is converted to pdf by either Acrobat Distiller™ or Ghostview.

Elenco dei parametri

psdoc
llx
lly
urx
ury
page
dest: The parameter dest determines how the document is being viewed. It can be fitpage, fitwidth, fitheight, or fitbbox.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

ps_add_launchlink()

ps_add_note

(PECL)

ps_add_note -- Adds note to current page

Descrizione

bool ps_add_note ( resource psdoc, float llx, float lly, float urx, float ury, string contents, string title, string icon, int open )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

ps_add_pdflink

(PECL)

ps_add_pdflink -- Adds link to a page in a second pdf document

Descrizione

bool ps_add_pdflink ( resource psdoc, float llx, float lly, float urx, float ury, string filename, int page, string dest )

Places a hyperlink at the given position pointing to a second pdf document. Clicking on the link will branch to the document at the given page. The first page in a document has number 1.

The hyperlink start is a rectangle with its lower left corner at (llx, lly) and its upper right corner at (urx, ury). The rectangle has by default a thin blue border.

The hyperlink will not be visible if the document is printed or viewed but it will show up if the document is converted to pdf by either Acrobat Distiller™ or Ghostview.

Elenco dei parametri

psdoc
llx
lly
urx
ury
filename
page
dest: The parameter dest determines how the document is being viewed. It can be fitpage, fitwidth, fitheight, or fitbbox.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

ps_add_launchlink()

ps_add_locallink()

ps_add_weblink

(PECL)

ps_add_weblink -- Adds link to a web location

Descrizione

bool ps_add_weblink ( resource psdoc, float llx, float lly, float urx, float ury, string url )

Places a hyperlink at the given position pointing to a web page. The hyperlink start is a rectangle with its lower left corner at (llx, lly) and its upper right corner at (urx, ury). The rectangle has by default a thin blue border.

The hyperlink will not be visible if the document is printed or viewed but it will show up if the document is converted to pdf by either Acrobat Distiller™ or Ghostview.

Valori restituiti

Starts a new page. Although the parameters width and height imply a different page size for each page, this is not possible in PostScript. The first call of ps_begin_page() will set the page size for the whole document. Consecutive calls will have no effect, except for creating a new page. The situation is different if you intent to convert the PostScript document into PDF. This function places pdfmarks into the document which can set the size for each page indiviually. The resulting PDF document will have different page sizes.

Each page is encapsulated into save/restore. This means, that most of the settings made on one page will not be retained on the next page.

If there is up to the first call of ps_begin_page() no call of ps_findfont(), then the header of the PostScript document will be output and the bounding box will be set to the size of the first page. If ps_findfont() was called before the header has been output already, the document will not have a valid bounding box. In order to prevent this, one should call ps_set_info() to set the info field BoundingBox and possibly Orientation before any ps_findfont() or ps_begin_page() calls.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

ps_end_page()

ps_findfont()

ps_set_info()

ps_begin_pattern

(PECL)

ps_begin_pattern -- Start a new pattern

Descrizione

bool ps_begin_pattern ( resource psdoc, float width, float height, float xstep, float ystep, int painttype )

Starts a new pattern.

Valori restituiti

The identifier of the pattern or FALSE in case of an error.

Vedere anche:

ps_end_pattern()

ps_setcolor()

ps_shading_pattern()

ps_begin_template

(PECL)

ps_begin_template -- Start a new template

Descrizione

bool ps_begin_template ( resource psdoc, float width, float height )

Starts a new template.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

ps_end_template()

ps_circle

(PECL)

ps_circle -- Draws a circle

Descrizione

bool ps_circle ( resource psdoc, float x, float y, float radius )

Draws a circle with its middle point at (x, y). The circle starts and ends at position (x+radius, y). If this function is called outside a path it will start a new path. If it is called within a path it will add the circle as a subpath. If the last drawing operation does not end in point (x+radius, y) then there will be a gap in the path.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

ps_arc()

ps_arcn()

ps_clip

(PECL)

ps_clip -- Clips drawing to current path

Descrizione

bool ps_clip ( resource psdoc )

Takes the current path and uses it to define the border of a clipping area.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

ps_closepath()

ps_close_image

(PECL)

ps_close_image -- Closes image and frees memory

Descrizione

void ps_close_image ( resource psdoc, int imageid )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Valori restituiti

Returns NULL on success or FALSE on failure.

Vedere anche:

ps_open_image()

ps_open_image_file()

ps_close

(PECL)

ps_close -- Closes a PostScript document

Descrizione

bool ps_close ( resource psdoc )

Closes the PostScript document.

This function outputs a last line into the PostScript document, which is a PostScript comment containing the number of pages. It also writes the bookmark tree.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

ps_open_file()

ps_delete()

ps_closepath_stroke

(PECL)

ps_closepath_stroke -- Closes and strokes path

Descrizione

bool ps_closepath_stroke ( resource psdoc )

Connects the last point with first point of a path and draws the resulting closed line.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

ps_closepath()

ps_closepath

(PECL)

ps_closepath -- Closes path

Descrizione

bool ps_closepath ( resource psdoc )

Connects the last point with first point of a path.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

Vedere anche:

ps_fill()

ps_stroke()

ps_fill

(PECL)

ps_fill -- Fills the current path

Descrizione

bool ps_fill ( resource psdoc )

Fills the path constructed with previously called drawing functions like ps_lineto().

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

ps_fill_stroke()

ps_stroke()

ps_findfont

(PECL)

ps_findfont -- Loads a font

Descrizione

int ps_findfont ( resource psdoc, string fontname, string encoding [, bool embed] )

Loads a font for later use. Before text is output with a loaded font it must be set with ps_setfont(). This function needs the adobe font metric file in order to calculate the space used up by the characters. A font which is loaded within a page will only be available on that page. Fonts which are to be used in the complete document have to be loaded before the first call of ps_begin_page(). Calling ps_findfont() between pages will make that font available for all following pages.

Elenco dei parametri

psdoc

fontname

encoding

ps_findfont() will try to load the file passed in the parameter encoding. Encoding files are of the same syntax as those used by dvips(1). They contain a font encoding vector (which is currently not used but must be present) and a list of extra ligatures to extend the list of ligatures derived from the afm file.

encoding can be NULL or the empty string if the default encoding (TeXBase1) shall be used.

If the encoding is set to builtin then there will be no reencoding and the font specific encoding will be used. This is very useful with symbol fonts.

embed

Valori restituiti

Returns the identifier of the font or zero in case of an error. The identifier is a positive number.

Vedere anche:

ps_begin_page()

ps_setfont()

ps_get_buffer

(PECL)

ps_get_buffer -- Fetches the full buffer containig the generated PS data

Descrizione

string ps_get_buffer ( resource psdoc )

Not yet implemented

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Vedere anche:

ps_open_file()

ps_get_parameter

(PECL)

ps_get_parameter -- Gets certain parameters

Descrizione

string ps_get_parameter ( resource psdoc, string name [, float modifier] )

Gets several parameters which were set by ps_set_parameter(). Parameters are by definition string values. This function cannot be used to retrieve resources which were also set by ps_set_parameter().

Valori restituiti

Returns the value of the parameter or FALSE.

Vedere anche:

ps_set_parameter()

ps_get_value

(PECL)

ps_get_value -- Gets certain values

Descrizione

float ps_get_value ( resource psdoc, string name [, float modifier] )

Gets several values which were set by ps_set_value(). Parameters are by definition float values.

Elenco dei parametri

psdoc
name
modifier: The parameter modifier specifies the resource for which the value is to be retrieved. This can be the id of a font or an image. It must be 0.0 if not used.

Valori restituiti

Returns the value of the parameter or FALSE.

Vedere anche:

ps_set_value()

ps_hyphenate

(PECL)

ps_hyphenate -- Hyphenates a word

Descrizione

array ps_hyphenate ( resource psdoc, string text )

Hyphenates the passed word. ps_hyphenate() evaluates the value hyphenminchars and the parameter hyphendict. hyphendict must be set before calling this function.

This function requires the locale category LC_CTYPE to be set properly. This is done when the extension is initialized by using the environment variables. On Unix systems read the man page of locale.

Elenco dei parametri

psdoc
text: text should not contain any non alpha characters. Possible positions for breaks are returned in an array of interger numbers. Each number is the position of the char in text after which a hyphenation can take place.

Vedere anche:

ps_show_boxed()

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

ps_close()

ps_open_image_file

(PECL)

ps_open_image_file -- Opens image from file

Descrizione

int ps_open_image_file ( resource psdoc, string type, string filename [, string stringparam [, int intparam]] )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Valori restituiti

Returns identifier of image or zero in case of an error. The identifier is a positive number greater than 0.

Vedere anche:

ps_open_image()

ps_place_image()

ps_close_image()

ps_open_image

(PECL)

ps_open_image -- Reads an image for later placement

Descrizione

int ps_open_image ( resource psdoc, string type, string source, string data, int lenght, int width, int height, int components, int bpc, string params )

Reads an image which is already available in memory. The parameter source is currently not evaluated and assumed to be memory.

Valori restituiti

Returns identifier of image or zero in case of an error. The identifier is a positive number greater than 0.

Vedere anche:

ps_open_image_file()

ps_place_image()

ps_close_image()

ps_place_image

(PECL)

ps_place_image -- Places image on the page

Descrizione

bool ps_place_image ( resource psdoc, int imageid, float x, float y, float scale )

Places a formerly loaded image on the page. The image can be scaled.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

ps_open_image()

ps_open_image_file()

ps_rect

(PECL)

ps_rect -- Draws a rectangle

Descrizione

bool ps_rect ( resource psdoc, float x, float y, float width, float height )

Draws a rectangle with its lower left corner at (x, y). The rectangle starts and ends in its lower left corner. If this function is called outside a path it will start a new path. If it is called within a path it will add the rectangle as a subpath. If the last drawing operation does not end in the lower left corner then there will be a gap in the path.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

ps_arc()

ps_cirle()

ps_lineto()

ps_restore

(PECL)

ps_restore -- Restore previously save context

Descrizione

bool ps_restore ( resource psdoc )

Restores a previously saved graphics context. Any call of ps_save() must be accompanied by a call to ps_restore().

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

ps_save()

ps_rotate

(PECL)

ps_rotate -- Sets rotation factor

Descrizione

bool ps_rotate ( resource psdoc, float rot )

Sets the rotation of the coordinate system.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

ps_scale()

ps_translate()

ps_save

(PECL)

ps_save -- Save current context

Descrizione

bool ps_save ( resource psdoc )

Saves the current graphics context, containing colors, translation and rotation settings and some more. A save context can be restored with ps_restore().

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

ps_set_border_color()

ps_set_border_style()

ps_set_border_style

(PECL)

ps_set_border_style -- Sets border style of annotations

Descrizione

bool ps_set_border_style ( resource psdoc, string style, float width )

Annotations like the starting points of links are surrounded by a rectangle. This function sets the appearance and width of the border line.

Elenco dei parametri

psdoc
style: style can be solid or dashed.
width

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

ps_set_border_color()

ps_set_border_dash()

ps_set_info

(PECL)

ps_set_info -- Sets information fields of document

Descrizione

Descrizione

bool ps_set_value ( resource psdoc, string name, float value )

Sets several values which are used by many functions. Parameters are by definition float values.

Elenco dei parametri

The name can be one of the following:

textrendering: The way how text is shown.
textx: The x coordinate for text output.
texty: The y coordinate for text output.
wordspacing: The distance between words relative to the width of a space.
leading: The distance between lines in pixels.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

ps_get_value()

ps_set_parameter()

ps_setcolor

(PECL)

ps_setcolor -- Sets current color

Descrizione

bool ps_setcolor ( resource psdoc, string type, string colorspace, float c1, float c2, float c3, float c4 )

Sets the color for drawing, filling, or both.

Elenco dei parametri

psdoc
type: The parameter type can be both, fill, or fillstroke.
colorspace: The colorspace should be one of gray, rgb, cmyk, spot, pattern. Depending on the colorspace either only the first, the first three or all parameters will be used.
c1
c2
c3
c4

Bugs

The second parameter is currently not always evaluated. The color is sometimes set for filling and drawing just as if fillstroke were passed.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

ps_setdash

(PECL)

ps_setdash -- Sets appearance of a dashed line

Descrizione

bool ps_setdash ( resource psdoc, float on, float off )

Sets the length of the black and white portions of a dashed line.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

ps_setpolydash()

ps_setflat

(PECL)

ps_setflat -- Sets flatness

Descrizione

bool ps_setflat ( resource psdoc, float value )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Elenco dei parametri

psdoc
value: The value must be between 0.2 and 1.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

ps_setfont

(PECL)

ps_setfont -- Sets font to use for following output

Descrizione

bool ps_setfont ( resource psdoc, int fontid, float size )

The identifier of the pattern or FALSE in case of an error.

Vedere anche:

ps_shading()

ps_shfill()

ps_shading

(PECL)

ps_shading -- Creates a shading for later use

Descrizione

int ps_shading ( resource psdoc, string type, float x0, float y0, float x1, float y1, float c1, float c2, float c3, float c4, string optlist )

Creates a shading, which can be used by ps_shfill() or ps_shading_pattern().

The color of the shading can be in any color space except for pattern.

Elenco dei parametri

psdoc
type: The type of shading can be either radial or axial. Each shading starts with the current fill color and ends with the given color values passed in the parameters c1 to c4 (see ps_setcolor() for their meaning).
x0, x1, y0, y1: The coordinates x0, y0, x1, y1 are the start and end point of the shading.
c1, c2, c3, c4: See ps_setcolor() for their meaning.
optlist: If the shading is of type radial the optlist must also contain the parameters r0 and r1 with the radius of the start and end circle.

Valori restituiti

Returns the identifier of the pattern or FALSE in case of an error.

Vedere anche:

ps_shading_pattern()

ps_shfill()

ps_shfill

(PECL)

ps_shfill -- Fills an area with a shading

Descrizione

bool ps_shfill ( resource psdoc, int shadingid )

Fills an area with a shading, which has to be created before with ps_shading().

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

ps_shading()

ps_shading_pattern()

ps_show_boxed

(PECL)

ps_show_boxed -- Output text in a box

Descrizione

int ps_show_boxed ( resource psdoc, string text, float left, float bottom, float width, float height, string hmode [, string feature] )

Outputs a text in a given box. The lower left corner of the box is at (left, bottom). Line breaks will be inserted where needed. Multiple spaces are treated as one. Tabulators are treated as spaces.

The text will be hyphenated if the parameter "hyphenation" is set to "true" and the parameter "hyphendict" contains a valid filename for a hyphenation file. The line spacing is taken from the value "leading". Paragraphs can be separated by an empty line just like in TeX. If the value "parindent" is set to value > 0.0 then the first n lines will be indented. The number n of lines is set by the parameter "numindentlines". In order to prevent indenting of the first m paragraphs set the value "parindentskip" to a positive number.

Used parameters

The output of ps_show_boxed() can be configured with several parameters and values which must be set with either ps_set_parameter() or ps_set_value(). Beside the parameters and values which affect text output the following parameters and values are evaluated.

leading (value): Distance between baselines of two consecutive lines.
linebreak (parameter): Set to "true" if you want a carriage return to start a new line instead of treating it as a space. Defaults to "false".
parbreak (parameter): Set to "true" if you want a carriage return on a single line to start a new paragraph instead of treating it as a space. Defaults to "true".
hyphenation (parameter): Set to "true" in order to turn hyphenation on. This requires a dictionary to be set with the parameter "hyphendict". Defaults to "false".
hyphendict (parameter): Filename of the dictionary used for hyphenation pattern (see below).
hyphenminchar (value): The number of chars which must at least be left over before or after the hyphen. This implies that only words of at least two times this value will be hyphenated. The default value is three. Setting a value of zero will result in the default value.
parindent (value): Set the amount of space in pixel for indenting the first m lines of a paragraph. m can be set with the value "numindentlines".
parskip (value): Set the amount of extra space in pixel between paragraphs. Defaults to 0 which will result in a normal line distance.
numindentlines (value): Number of lines from the start of the paragraph which will be indented. Defaults to 1.
parindentskip (value): Number of paragraphs in the box whose first lines will not be indented. This defaults to 0. This is useful for paragraphs right after a section heading or text being continued in a second box. In both case one would set this to 1.
linenumbermode (parameter): Set how lines are to be numbered. Possible values are "box" for numbering lines in the whole box or "paragraph" to number lines within each paragraph.
linenumberspace (value): The space for the column left of the numbered line containing the line number. The line number will be right justified into this column. Defaults to 20.
linenumbersep (value): The space between the column with line numbers and the line itself. Defaults to 5.

Hyphenation

Text is hyphenated if the parameter hyphenation is set to true and a valid hyphenation dictionary is set. pslib does not ship its own hyphenation dictionary but uses one from openoffice, scribus or koffice. You can find their dictionaries for different languages in one of the following directories if the software is installed:

/usr/share/apps/koffice/hyphdicts/

/usr/lib/scribus/dicts/

/usr/lib/openoffice/share/dict/ooo/

Currently scribus appears to have the most complete hyphenation dictionaries.

Elenco dei parametri

psdoc
text
left
bottom
width
height
hmode: The parameter hmode can be "justify", "fulljustify", "right", "left", or "center". The difference of "justify" and "fulljustify" just affects the last line of the box. In fulljustify mode the last line will be left and right justified unless this is also the last line of paragraph. In justify mode it will always be left justified.
feature

Valori restituiti

Number of characters that could not be written.

Vedere anche:

ps_show_xy

(PECL)

ps_show_xy -- Output text at given position

Descrizione

bool ps_show_xy ( resource psdoc, string text, float x, float y )

Output a text at the given text position.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

ps_show()

ps_show

(PECL)

ps_show -- Output text

Descrizione

bool ps_show ( resource psdoc, string text )

Output a text at the current text position. The function will issue an error if no font was set before with ps_setfont().

ps_show() evaluates the following parameters and values as set by ps_set_parameter() and ps_set_value().

charspacing (value): Distance between two consecutive glyphs. If this value is unequal to zero then all ligatures will be resolved. Values less than zero are allowed.
kerning (parameter): Setting this parameter to "false" will turn off kerning. Kerning is turned on by default.
ligatures (parameter): Setting this parameter to "false" will turn off the use of ligatures. Ligatures are turned on by default.
underline (parameter): Setting this parameter to "true" will turn on underlining. Underlining is turned off by default.
overline (parameter): Setting this parameter to "true" will turn on overlining. Overlining is turned off by default.
strikeout (parameter): Setting this parameter to "true" will turn on striking out. Striking out is turned off by default.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

ps_show_xy()

ps_setfont()

ps_string_geometry

(PECL)

ps_string_geometry -- Gets geometry of a string

Descrizione

array ps_string_geometry ( resource psdoc, string text [, int fontid [, float size]] )

This function is similar to ps_stringwidth() but returns an array of dimensions.

Valori restituiti

An array of the dimensions of a string. The element 'width' contains the width of the string as returned by ps_stringwidth(). The element 'descender' contains the maximum descender and 'ascender' the maximum ascender of the string.

Vedere anche:

readline_callback_handler_remove(), readline_callback_read_char() e stream_select().

ps_stringwidth()

ps_stringwidth

(PECL)

ps_stringwidth -- Gets width of a string

Descrizione

float ps_stringwidth ( resource psdoc, string text [, int fontid [, float size]] )

Calculates the width of a string in points if it was output in the given font and font size. This function needs an Adobe font metrics file to calculate the precise width. If kerning is turned on, it will be taken into account.

Valori restituiti

Width of a string in points.

Vedere anche:

ps_string_geometry()

ps_stroke

(PECL)

ps_stroke -- Draws the current path

Descrizione

bool ps_stroke ( resource psdoc )

Draws the path constructed with previously called drawing functions like ps_lineto().

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

ps_closepath_stroke()

ps_fill()

ps_fill_stroke()

ps_symbol_name

(PECL)

ps_symbol_name -- Gets name of a glyph

Descrizione

string ps_symbol_name ( resource psdoc, int ord [, int fontid] )

This function needs an Adobe font metrics file to know which glyphs are available.

Elenco dei parametri

psdoc
ord: The parameter ord is the position of the glyph in the font encoding vector.
fontid

Valori restituiti

The name of a glyph in the given font.

Vedere anche:

ps_symbol()

ps_symbol_width()

ps_symbol_width

(PECL)

ps_symbol_width -- Gets width of a glyph

Descrizione

float ps_symbol_width ( resource psdoc, int ord [, int fontid [, float size]] )

Calculates the width of a glyph in points if it was output in the given font and font size. This function needs an Adobe font metrics file to calculate the precise width.

Elenco dei parametri

psdoc
ord: The parameter ord is the position of the glyph in the font encoding vector.
fontid: Its description
size

Valori restituiti

The width of a glyph in points.

Vedere anche:

ps_symbol()

ps_symbol_name()

ps_symbol

(PECL)

ps_symbol -- Output a glyph

Descrizione

bool ps_symbol ( resource psdoc, int ord )

Output the glyph at position ord in the font encoding vector of the current font. The font encoding for a font can be set when loading the font with ps_findfont().

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

ps_symbol_name()

ps_symbol_width()

ps_translate

(PECL)

ps_translate -- Sets translation

Descrizione

bool ps_translate ( resource psdoc, float x, float y )

Sets a new initial point of the coordinate system.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

ps_scale()

ps_rotate()

CXIX. Pspell Functions

Introduzione

These functions allow you to check the spelling of a word and offer suggestions.

Requisiti

To compile PHP with pspell support, you need the aspell library, available from http://aspell.sourceforge.net/.

Installazione

If you have the libraries needed add the --with-pspell[=dir] option when compiling PHP.

Note to Win32 Users: win32 support is available only in PHP 4.3.3 and later versions. Also, you must have aspell 0.50 or newer installed. In order to enable this module under Windows, you must copy aspell-15.dll from the bin folder of your aspell installation to a folder where PHP will be able to find it. C:\PHP or the SYSTEM32 folder of your windows machine (Ex: C:\WINNT\SYSTEM32 or C:\WINDOWS\SYSTEM32) are good choices.

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

PSPELL_FAST (integer)
PSPELL_NORMAL (integer)
PSPELL_BAD_SPELLERS (integer)
PSPELL_RUN_TOGETHER (integer)

Sommario
pspell_add_to_personal -- Add the word to a personal wordlist
pspell_add_to_session -- Add the word to the wordlist in the current session
pspell_check -- Check a word
pspell_clear_session -- Clear the current session
pspell_config_create -- Create a config used to open a dictionary
pspell_config_data_dir -- location of language data files
pspell_config_dict_dir -- Location of the main word list
pspell_config_ignore -- Ignore words less than N characters long
pspell_config_mode -- Change the mode number of suggestions returned
pspell_config_personal -- Set a file that contains personal wordlist
pspell_config_repl -- Set a file that contains replacement pairs
pspell_config_runtogether -- Consider run-together words as valid compounds
pspell_config_save_repl -- Determine whether to save a replacement pairs list along with the wordlist
pspell_new_config -- Load a new dictionary with settings based on a given config
pspell_new_personal -- Load a new dictionary with personal wordlist
pspell_new -- Load a new dictionary
pspell_save_wordlist -- Save the personal wordlist to a file
pspell_store_replacement -- Store a replacement pair for a word
pspell_suggest -- Suggest spellings of a word

pspell_add_to_personal

(PHP 4 >= 4.0.2, PHP 5)

pspell_add_to_personal -- Add the word to a personal wordlist

Description

bool pspell_add_to_personal ( int dictionary_link, string word )

pspell_add_to_personal() adds a word to the personal wordlist. If you used pspell_new_config() with pspell_config_personal() to open the dictionary, you can save the wordlist later with pspell_save_wordlist(). Please, note that this function will not work unless you have pspell .11.2 and aspell .32.5 or later.

Esempio 1. pspell_add_to_personal()
<?php $pspell_config = pspell_config_create("en"); pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws"); $pspell_link = pspell_new_config($pspell_config); pspell_add_to_personal($pspell_link, "Vlad"); pspell_save_wordlist($pspell_link); ?>

pspell_add_to_session

(PHP 4 >= 4.0.2, PHP 5)

pspell_add_to_session -- Add the word to the wordlist in the current session

Description

bool pspell_add_to_session ( int dictionary_link, string word )

pspell_add_to_session() adds a word to the wordlist associated with the current session. It is very similar to pspell_add_to_personal()

pspell_check

(PHP 4 >= 4.0.2, PHP 5)

pspell_check -- Check a word

Description

bool pspell_check ( int dictionary_link, string word )

pspell_check() checks the spelling of a word and returns TRUE if the spelling is correct, FALSE if not.

Esempio 1. pspell_check()
<?php $pspell_link = pspell_new("en"); if (pspell_check($pspell_link, "testt")) { echo "This is a valid spelling"; } else { echo "Sorry, wrong spelling"; } ?>

pspell_clear_session

(PHP 4 >= 4.0.2, PHP 5)

pspell_clear_session -- Clear the current session

Description

bool pspell_clear_session ( int dictionary_link )

pspell_clear_session() clears the current session. The current wordlist becomes blank, and, for example, if you try to save it with pspell_save_wordlist(), nothing happens.

pspell_config_create

(PHP 4 >= 4.0.2, PHP 5)

pspell_config_create -- Create a config used to open a dictionary

Description

int pspell_config_create ( string language [, string spelling [, string jargon [, string encoding]]] )

pspell_config_create() has a very similar syntax to pspell_new(). In fact, using pspell_config_create() immediately followed by pspell_new_config() will produce the exact same result. However, after creating a new config, you can also use pspell_config_*() functions before calling pspell_new_config() to take advantage of some advanced functionality.

The language parameter is the language code which consists of the two letter ISO 639 language code and an optional two letter ISO 3166 country code after a dash or underscore.

The spelling parameter is the requested spelling for languages with more than one spelling such as English. Known values are 'american', 'british', and 'canadian'.

The jargon parameter contains extra information to distinguish two different words lists that have the same language and spelling parameters.

The encoding parameter is the encoding that words are expected to be in. Valid values are 'utf-8', 'iso8859-*', 'koi8-r', 'viscii', 'cp1252', 'machine unsigned 16', 'machine unsigned 32'. This parameter is largely untested, so be careful when using.

The mode parameter is the mode in which spellchecker will work. There are several modes available:

PSPELL_FAST - Fast mode (least number of suggestions)
PSPELL_NORMAL - Normal mode (more suggestions)
PSPELL_BAD_SPELLERS - Slow mode (a lot of suggestions)

pspell_config_mode() should be used on a config before calling pspell_new_config(). This function determines how many suggestions will be returned by pspell_suggest().

The mode parameter is the mode in which spellchecker will work. There are several modes available:

PSPELL_FAST - Fast mode (least number of suggestions)
PSPELL_NORMAL - Normal mode (more suggestions)
PSPELL_BAD_SPELLERS - Slow mode (a lot of suggestions)

pspell_new_config

(PHP 4 >= 4.0.2, PHP 5)

pspell_new_config -- Load a new dictionary with settings based on a given config

Description

int pspell_new_config ( int config )

pspell_new_config() opens up a new dictionary with settings specified in a config, created with pspell_config_create() and modified with pspell_config_*() functions. This method provides you with the most flexibility and has all the functionality provided by pspell_new() and pspell_new_personal().

The config parameter is the one returned by pspell_config_create() when the config was created.

Esempio 1. pspell_new_config()
<?php $pspell_config = pspell_config_create("en"); pspell_config_personal($pspell_config, "/var/dictionaries/custom.pws"); pspell_config_repl($pspell_config, "/var/dictionaries/custom.repl"); $pspell_link = pspell_new_config($pspell_config); ?>

pspell_new_personal

(PHP 4 >= 4.0.2, PHP 5)

pspell_new_personal -- Load a new dictionary with personal wordlist

Description

int pspell_new_personal ( string personal, string language [, string spelling [, string jargon [, string encoding [, int mode]]]] )

pspell_new_personal() opens up a new dictionary with a personal wordlist and returns the dictionary link identifier for use in other pspell functions. The wordlist can be modified and saved with pspell_save_wordlist(), if desired. However, the replacement pairs are not saved. In order to save replacement pairs, you should create a config using pspell_config_create(), set the personal wordlist file with pspell_config_personal(), set the file for replacement pairs with pspell_config_repl(), and open a new dictionary with pspell_new_config().

The personal parameter specifies the file where words added to the personal list will be stored. It should be an absolute filename beginning with '/' because otherwise it will be relative to $HOME, which is "/root" for most systems, and is probably not what you want.

The language parameter is the language code which consists of the two letter ISO 639 language code and an optional two letter ISO 3166 country code after a dash or underscore.

The spelling parameter is the requested spelling for languages with more than one spelling such as English. Known values are 'american', 'british', and 'canadian'.

The jargon parameter contains extra information to distinguish two different words lists that have the same language and spelling parameters.

The mode parameter is the mode in which spellchecker will work. There are several modes available:

PSPELL_FAST - Fast mode (least number of suggestions)
PSPELL_NORMAL - Normal mode (more suggestions)
PSPELL_BAD_SPELLERS - Slow mode (a lot of suggestions)
PSPELL_RUN_TOGETHER - Consider run-together words as legal compounds. That is, "thecat" will be a legal compound, although there should be a space between the two words. Changing this setting only affects the results returned by pspell_check(); pspell_suggest() will still return suggestions.

Mode is a bitmask constructed from different constants listed above. However, PSPELL_FAST, PSPELL_NORMAL and PSPELL_BAD_SPELLERS are mutually exclusive, so you should select only one of them.

For more information and examples, check out inline manual pspell website:http://aspell.net/.

Esempio 1. pspell_new_personal()
<?php $pspell_link = pspell_new_personal ("/var/dictionaries/custom.pws", "en", "", "", "", PSPELL_FAST|PSPELL_RUN_TOGETHER); ?>

pspell_new

(PHP 4 >= 4.0.2, PHP 5)

pspell_new -- Load a new dictionary

Description

int pspell_new ( string language [, string spelling [, string jargon [, string encoding [, int mode]]]] )

pspell_new() opens up a new dictionary and returns the dictionary link identifier for use in other pspell functions.

The language parameter is the language code which consists of the two letter ISO 639 language code and an optional two letter ISO 3166 country code after a dash or underscore.

The spelling parameter is the requested spelling for languages with more than one spelling such as English. Known values are 'american', 'british', and 'canadian'.

The jargon parameter contains extra information to distinguish two different words lists that have the same language and spelling parameters.

The mode parameter is the mode in which spellchecker will work. There are several modes available:

PSPELL_FAST - Fast mode (least number of suggestions)
PSPELL_NORMAL - Normal mode (more suggestions)
PSPELL_BAD_SPELLERS - Slow mode (a lot of suggestions)
PSPELL_RUN_TOGETHER - Consider run-together words as legal compounds. That is, "thecat" will be a legal compound, although there should be a space between the two words. Changing this setting only affects the results returned by pspell_check(); pspell_suggest() will still return suggestions.

array pspell_suggest ( int dictionary_link, string word )

pspell_suggest() returns an array of possible spellings for the given word.

Esempio 1. pspell_suggest() example
<?php $pspell_link = pspell_new("en"); if (!pspell_check($pspell_link, "testt")) { $suggestions = pspell_suggest($pspell_link, "testt"); foreach ($suggestions as $suggestion) { echo "Possible spelling: $suggestion<br />"; } } ?>

CXX. Funzioni qtdom

Avvertimento

Nota: Questo modulo non è disponibile su piattaforme Windows.

Nota: Questo modulo è stato spostato nel repository PECL e non sarà più rilascio con il PHP dalla versione 5.0.0.

Requisiti

E' richiesta la libreria Qt-library >=2.2.0

Installazione

Per utilizzare questo modulo, configurare il PHP con --with-qtdom.

Sommario
qdom_error -- Restituisce la stringa d'errore dell'ultima operazione QDOM o FALSE se non ci sono stati errori
qdom_tree -- Crea un tree di una stringa XML

qdom_error

(PHP 4 >= 4.0.5, PECL)

qdom_error -- Restituisce la stringa d'errore dell'ultima operazione QDOM o FALSE se non ci sono stati errori

Descrizione

string qdom_error ( void )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

qdom_tree

(PHP 4 >= 4.0.4, PECL)

qdom_tree -- Crea un tree di una stringa XML

Descrizione

QDomDocument qdom_tree ( string doc )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

CXXI. Radius

Introduzione

This package is based on the libradius of FreeBSD. This PECL 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.

Nota: An exact description for libradius can be found here. A detailed description of the configuration file can be found here.

Installazione

Howto install the package?

untar the package (usually into php4/ext)
rename radius-x.x to radius
run ./buildconf in php4
run ./configure --enable-radius
make; make install

or if you would like to have it as .so:

untar the package
run phpize in the radius-x.x directory
run ./configure in the radius-x.x directory
make; make install

For windows I recommend to use the php_radius.dll from http://snaps.php.net/. You may obtain this unbundled PECL extension from the various PECL snaps pages (select the appropriate repository for your version of PHP): PECL for PHP 4.3.x, PECL for PHP 5.0.x or PECL Unstable.

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

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_LOGIN

RADIUS_FRAMED

RADIUS_CALLBACK_LOGIN

RADIUS_CALLBACK_FRAMED

RADIUS_OUTBOUND

RADIUS_ADMINISTRATIVE

RADIUS_NAS_PROMPT

RADIUS_AUTHENTICATE_ONLY

RADIUS_CALLBACK_NAS_PROMPT

RADIUS_FRAMED_PROTOCOL (int)

Framed Protocol, one of:

RADIUS_PPP

RADIUS_SLIP

RADIUS_ARAP

RADIUS_GANDALF

RADIUS_XYLOGICS

RADIUS_FRAMED_IP_ADDRESS (string)

IP-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_NONE

RADIUS_COMP_VJ

RADIUS_COMP_IPXHDR

RADIUS_LOGIN_IP_HOST (string)

RADIUS_LOGIN_SERVICE (int)

RADIUS_LOGIN_TCP_PORT (int)

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)

RADIUS_LOGIN_LAT_NODE (int)

RADIUS_LOGIN_LAT_GROUP (int)

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_ASYNC

RADIUS_SYNC

RADIUS_ISDN_SYNC

RADIUS_ISDN_ASYNC_V120

RADIUS_ISDN_ASYNC_V110

RADIUS_VIRTUAL

RADIUS_PIAFS

RADIUS_HDLC_CLEAR_CHANNEL

RADIUS_X_25

RADIUS_X_75

RADIUS_G_3_FAX

RADIUS_SDSL

RADIUS_ADSL_CAP

RADIUS_ADSL_DMT

RADIUS_IDSL

RADIUS_ETHERNET

RADIUS_XDSL

RADIUS_CABLE

RADIUS_WIRELESS_OTHER

RADIUS_WIRELESS_IEEE_802_11

RADIUS_PORT_LIMIT (int)

Port Limit

RADIUS_LOGIN_LAT_PORT (int)

RADIUS_CONNECT_INFO (string)

Connect info

RADIUS_ACCT_STATUS_TYPE (int)

Accounting status type, one of:

RADIUS_START

RADIUS_STOP

RADIUS_ACCOUNTING_ON

RADIUS_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_RADIUS

RADIUS_AUTH_LOCAL

RADIUS_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_REQUEST

RADIUS_TERM_LOST_CARRIER

RADIUS_TERM_LOST_SERVICE

RADIUS_TERM_IDLE_TIMEOUT

RADIUS_TERM_SESSION_TIMEOUT

RADIUS_TERM_ADMIN_RESET

RADIUS_TERM_ADMIN_REBOOT

RADIUS_TERM_PORT_ERROR

RADIUS_TERM_NAS_ERROR

RADIUS_TERM_NAS_REQUEST

RADIUS_TERM_NAS_REBOOT

RADIUS_TERM_PORT_UNNEEDED

RADIUS_TERM_PORT_PREEMPTED

RADIUS_TERM_PORT_SUSPENDED

RADIUS_TERM_SERVICE_UNAVAILABLE

RADIUS_TERM_CALLBACK

RADIUS_TERM_USER_ERROR

RADIUS_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_RESPONSE

RADIUS_MICROSOFT_MS_CHAP_ERROR

RADIUS_MICROSOFT_MS_CHAP_PW_1

RADIUS_MICROSOFT_MS_CHAP_PW_2

RADIUS_MICROSOFT_MS_CHAP_LM_ENC_PW

RADIUS_MICROSOFT_MS_CHAP_NT_ENC_PW

RADIUS_MICROSOFT_MS_MPPE_ENCRYPTION_POLICY

RADIUS_MICROSOFT_MS_MPPE_ENCRYPTION_TYPES

RADIUS_MICROSOFT_MS_RAS_VENDOR

RADIUS_MICROSOFT_MS_CHAP_DOMAIN

RADIUS_MICROSOFT_MS_CHAP_CHALLENGE

RADIUS_MICROSOFT_MS_CHAP_MPPE_KEYS

RADIUS_MICROSOFT_MS_BAP_USAGE

RADIUS_MICROSOFT_MS_LINK_UTILIZATION_THRESHOLD

RADIUS_MICROSOFT_MS_LINK_DROP_TIME_LIMIT

RADIUS_MICROSOFT_MS_MPPE_SEND_KEY

RADIUS_MICROSOFT_MS_MPPE_RECV_KEY

RADIUS_MICROSOFT_MS_RAS_VERSION

RADIUS_MICROSOFT_MS_OLD_ARAP_PASSWORD

RADIUS_MICROSOFT_MS_NEW_ARAP_PASSWORD

RADIUS_MICROSOFT_MS_ARAP_PASSWORD_CHANGE_REASON

RADIUS_MICROSOFT_MS_FILTER

RADIUS_MICROSOFT_MS_ACCT_AUTH_TYPE

RADIUS_MICROSOFT_MS_ACCT_EAP_TYPE

RADIUS_MICROSOFT_MS_CHAP2_RESPONSE

RADIUS_MICROSOFT_MS_CHAP2_SUCCESS

RADIUS_MICROSOFT_MS_CHAP2_PW

RADIUS_MICROSOFT_MS_PRIMARY_DNS_SERVER

RADIUS_MICROSOFT_MS_SECONDARY_DNS_SERVER

RADIUS_MICROSOFT_MS_PRIMARY_NBNS_SERVER

RADIUS_MICROSOFT_MS_SECONDARY_NBNS_SERVER

RADIUS_MICROSOFT_MS_ARAP_CHALLENGE

Quickstart

Howto start?

get a radius resource
configure the library
create the request
put attributes
send the request
receive attributes
close the radius resource (optional)

Take also a look at the examples in this package.

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.

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. Binaries for Windows can be downloaded from here.

Sommario
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

radius_acct_open

(PECL)

radius_acct_open -- Creates a Radius handle for accounting

Descrizione

resource radius_acct_open ( void )

Valori restituiti

Returns a handle on success, FALSE on error. This function only fails if insufficient memory is available.

Esempi

Esempio 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_add_server -- Adds a server

Descrizione

bool radius_add_server ( resource 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.

Elenco dei parametri

radius_handle
hostname: The hostname parameter specifies the server host, either as a fully qualified domain name or as a dotted-quad IP address in text form.
port: The port specifies the UDP port to contact on the server. If port is given as 0, the library looks up the radius/udp or radacct/udp service 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 secret parameter. 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 timeout parameter, in units of seconds.
max_tries: The maximum number of repeated requests to make before giving up is passed into the max_tries.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 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; } ?>

Vedere anche:

radius_config()

radius_auth_open

(PECL)

radius_auth_open -- Creates a Radius handle for authentication

Descrizione

resource radius_auth_open ( void )

Valori restituiti

Returns a handle on success, FALSE on error. This function only fails if insufficient memory is available.

Esempi

Esempio 1. radius_auth_open() example
<?php $radh = radius_auth_open() or die ("Could not create handle"); echo "Handle successfully created"; ?>

radius_close

(PECL)

radius_close -- Frees all ressources

Descrizione

bool radius_close ( resource radius_handle )

It is not needed to call this function because php frees all resources at the end of each request.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

radius_config

(PECL)

radius_config -- Causes the library to read the given configuration file

Descrizione

bool radius_config ( resource 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.

Elenco dei parametri

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().

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

radius_add_server()

radius_create_request

(PECL)

radius_create_request -- Create accounting or authentication request

Descrizione

bool radius_create_request ( resource 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().

Nota: Attention: You must call this function, before you can put any attribute!

Elenco dei parametri

radius_handle: Type is RADIUS_ACCESS_REQUEST or RADIUS_ACCOUNTING_REQUEST.
type: Its description

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 1. radius_create_request() example
<?php if (!radius_create_request($res, RADIUS_ACCESS_REQUEST)) { echo 'RadiusError:' . radius_strerror($res). "\n<br />"; exit; } ?>

Valori restituiti

Returns an associative array containing the attribute-type and the data, or error number <= 0.

Esempi

Esempio 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)); } ?>

Vedere anche:

radius_put_attr()

radius_get_vendor_attr()

radius_put_vendor_attr()

radius_send_request()

radius_get_vendor_attr

(PECL)

radius_get_vendor_attr -- Extracts a vendor specific attribute

Descrizione

array radius_get_vendor_attr ( string data )

If radius_get_attr() returns RADIUS_VENDOR_SPECIFIC, radius_get_vendor_attr() may be called to determine the vendor.

Valori restituiti

Returns an associative array containing the attribute-type, vendor and the data, or FALSE on error.

Esempi

Esempio 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)); } } } ?>

Vedere anche:

radius_get_attr()

radius_put_vendor_attr()

radius_put_addr

(PECL)

radius_put_addr -- Attaches an IP-Address attribute

Descrizione

bool radius_put_addr ( resource radius_handle, int type, string addr )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

radius_put_attr

(PECL)

radius_put_attr -- Attaches a binary attribute

Descrizione

bool radius_put_attr ( resource radius_handle, int type, string value )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 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; } ?>

Vedere anche:

radius_get_attr()

radius_get_vendor_attr()

radius_put_vendor_attr()

radius_put_int

(PECL)

radius_put_int -- Attaches an integer attribute

Descrizione

bool radius_put_int ( resource radius_handle, int type, int value )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 1. radius_put_int() example
<?php if (!radius_put_int($res, RAD_FRAMED_PROTOCOL, RAD_PPP)) { echo 'RadiusError:' . radius_strerror($res). "\n<br />"; exit; } ?>

Vedere anche:

radius_put_string()

radius_put_vendor_int()

radius_put_vendor_string()

radius_put_string

(PECL)

radius_put_string -- Attaches a string attribute

Descrizione

bool radius_put_string ( resource radius_handle, int type, string value )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 1. radius_put_string() example
<?php if (!radius_put_string($res, RADIUS_USER_NAME, 'billy')) { echo 'RadiusError:' . radius_strerror($res). "\n<br />"; exit; } ?>

Vedere anche:

radius_put_int()

radius_put_vendor_int()

radius_put_vendor_string()

radius_put_vendor_addr

(PECL)

radius_put_vendor_addr -- Attaches a vendor specific IP-Address attribute

Descrizione

bool radius_put_vendor_addr ( resource radius_handle, int vendor, int type, string addr )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

radius_put_vendor_attr

(PECL)

radius_put_vendor_attr -- Attaches a vendor specific binary attribute

Descrizione

bool radius_put_vendor_attr ( resource radius_handle, int vendor, int type, string value )

Avvertimento

string radius_request_authenticator ( resource radius_handle )

The request authenticator is needed for demangling mangled data like passwords and encryption-keys.

Valori restituiti

Returns the request authenticator as string, or FALSE on error.

Vedere anche:

radius_demangle()

radius_send_request

(PECL)

radius_send_request -- Sends the request and waites for a reply

Descrizione

int radius_send_request ( resource 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.

Valori restituiti

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.

Vedere anche:

radius_create_request()

radius_server_secret

(PECL)

radius_server_secret -- Returns the shared secret

Descrizione

string radius_server_secret ( resource radius_handle )

The shared secret is needed as salt for demangling mangled data like passwords and encryption-keys.

Valori restituiti

Returns the server's shared secret as string, or FALSE on error.

radius_strerror

(PECL)

radius_strerror -- Returns an error message

Descrizione

string radius_strerror ( resource radius_handle )

If Radius-functions fail then they record an error message. This error message can be retrieved with this function.

Valori restituiti

Returns error messages as string from failed radius functions.

CXXII. Rar Functions

Introduzione

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 UnRar library and is directly prohibited by it's license.

More information about Rar and UnRar can be found at http://www.rarlabs.com/.

Requisiti

Non sono necessarie librerie esterne per utilizzare questo modulo.

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Installazione

Rar is currently available through PECL http://pecl.php.net/package/rar.

Also you can use the pear installer to install the Rar extension, using the following command: pear -v install rar.

You can always download the tar.gz package and install Rar by hand:
Esempio 1. Rar installation
gunzip rar-xxx.tgz tar -xvf rar-xxx.tar cd rar-xxx phpize ./configure && make && make install

Windows users can download the extension dll php_rar.dll here: http://snaps.php.net/win32/PECL_STABLE/.

Tipi di risorse

There is one resource used in Rar extension: a file descriptor returned by rar_open().

Costanti predefinite

RAR_HOST_MSDOS (integer)
RAR_HOST_OS2 (integer)
RAR_HOST_WIN32 (integer)
RAR_HOST_UNIX (integer)
RAR_HOST_BEOS (integer)

Esempi

Esempio 2. Rar extension overview 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.

Sommario
rar_close -- Close Rar archive and free all resources
rar_entry_get -- Get entry object from the Rar archive
Rar::extract -- Extract entry from the archive
Rar::getAttr -- Get attributes of the entry
Rar::getCrc -- Get CRC of the entry
Rar::getFileTime -- Get entry last modification time
Rar::getHostOs -- Get entry host OS
Rar::getMethod -- Get pack method of the entry
Rar::getName -- Get name of the entry
Rar::getPackedSize -- Get packed size of the entry
Rar::getUnpackedSize -- Get unpacked size of the entry
Rar::getVersion -- Get version of the archiver used to add the entry
rar_list -- Get entries list from the Rar archive
rar_open -- Open Rar archive

rar_close

(no version information, might be only in CVS)

rar_close -- Close Rar archive and free all resources

Description

rar_open() returns Rar file resource or FALSE on error.

CXXIII. GNU Readline

Introduzione

The readline() functions implement an interface to the GNU Readline library. These are functions that provide editable command lines. An example being the way Bash allows you to use the arrow keys to insert characters or scroll through command history. 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 used from a command line.

Nota: Questo modulo non è disponibile su piattaforme Windows.

Requisiti

To use the readline functions, you need to install libreadline. You can find libreadline on the home page of the GNU Readline project, at http://cnswww.cns.cwru.edu/~chet/readline/rltop.html. It's maintained by Chet Ramey, who's also the author of Bash.

You can also use these functions with the libedit library, a non-GPL replacement for the readline library. The libedit library is BSD licensed and available for download from http://sourceforge.net/projects/libedit/.

Installazione

To use these functions you must compile the CGI or CLI version of PHP with readline support. You need to configure PHP --with-readline[=DIR]. In order you want to use the libedit readline replacement, configure PHP --with-libedit[=DIR].

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

Questa estensione non definisce alcuna costante.

Sommario
readline_add_history -- Adds a line to the history
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 -- Clears the history
readline_completion_function -- Registers a completion function
readline_info -- Gets/sets various internal readline variables
readline_list_history -- Lists the history
readline_on_new_line -- Inform readline that the cursor has moved to a new line
readline_read_history -- Reads the history
readline_redisplay -- Ask readline to redraw the display
readline_write_history -- Writes the history
readline -- Reads a line

readline_add_history

(PHP 4, PHP 5)

readline_add_history -- Adds a line to the history

Description

bool readline_add_history ( string line )

This function adds a line to the command line history.

readline_callback_handler_install

(PHP 5 >= 5.1.0RC1)

readline_callback_handler_install -- Initializes the readline callback interface and terminal, prints the prompt and returns immediately

Descrizione

bool readline_callback_handler_install ( string prompt, callback callback )

Sets up a readline callback interface then prints prompt and immediately returns. The callback function takes one parameter; the user input returned. 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().

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 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) { $n = stream_select($r = array(STDIN), $w = null, $e = null, 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"; ?>

Vedere anche:

readline_callback_handler_remove

(PHP 5 >= 5.1.0RC1)

readline_callback_handler_remove -- Removes a previously installed callback handler and restores terminal settings

Descrizione

bool readline_callback_handler_remove ( void )

Removes a previously installed callback handler and restores terminal settings.

Esempi

See readline_callback_handler_install() for an example of how to use the readline callback interface.

Valori restituiti

Returns TRUE if a previously installed callback handler was removed, or FALSE if one could not be found.

Vedere anche:

readline_callback_handler_install(), and readline_callback_read_char().

readline_callback_read_char

(PHP 5 >= 5.1.0RC1)

readline_callback_read_char -- Reads a character and informs the readline callback interface when a line is received

Descrizione

void readline_callback_read_char ( void )

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.

Esempi

See readline_callback_handler_install() for an example of how to use the readline callback interface.

string readline ( string prompt )

This function returns a single string from the user. You may specify a string with which to prompt the user. The line returned has the ending newline removed. You must add this line to the history yourself using readline_add_history().

Esempio 1. readline()

<?php
//get 3 commands from user
for ($i=0; $i < 3; $i++) {
        $line = readline("Command: ");
        readline_add_history($line);
}

//dump history
print_r(readline_list_history());

//dump variables
print_r(readline_info());
?>

CXXIV. GNU Recode Functions

Introduzione

This module contains an interface to the GNU Recode library. The GNU Recode library converts files between various coded character sets and surface encodings. When this cannot be achieved exactly, it may get rid of the offending characters or fall back on approximations. The library recognises or produces nearly 150 different character sets and is able to convert files between almost any pair. Most RFC 1345 character sets are supported.

Nota: Questo modulo non è disponibile su piattaforme Windows.

Requisiti

You must have GNU Recode 3.5 or higher installed on your system. You can download the package from http://directory.fsf.org/All_GNU_Packages/recode.html.

Avvertimento

The Recode library version 3.6 adds weird characters behind converted strings under certain circumstances. Thus it's safer to use Recode v3.5 or one of the available alternatives like the iconv or mbstring extension.

Installazione

To be able to use the functions defined in this module you must compile your PHP interpreter using the --with-recode[=DIR] option.

Avvertimento

Crashes and startup problems of PHP may be encountered when loading the recode as extension after loading any extension of mysql or imap. Loading the recode before those extension has proved to fix the problem. This is due a technical problem that both the c-client library used by imap and recode have their own hash_lookup() function and both mysql and recode have their own hash_insert function.

Avvertimento

Il modulo IMAP non può essere utilizzato in congiunzione con i moduli recode, YAZ oppure Cyrus. Poichè questi moduli condividono i medesimi simboli interni.

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

Questa estensione non definisce alcuna costante.

Sommario
recode_file -- Recode from file to file according to recode request
recode_string -- Recode a string according to a recode request
recode -- Alias di recode_string()

recode_file

(PHP 3 >= 3.0.13, PHP 4, PHP 5)

recode_file -- Recode from file to file according to recode request

Description

bool recode_file ( string request, resource input, resource output )

Recode the file referenced by file handle input into the file referenced by file handle output according to the recode request. Returns FALSE, if unable to comply, TRUE otherwise.

This function does not currently process filehandles referencing remote files (URLs). Both filehandles must refer to local files.

Esempio 1. Basic recode_file() example
<?php $input = fopen('input.txt', 'r'); $output = fopen('output.txt', 'w'); recode_file("us..flat", $input, $output); ?>

recode_string

(PHP 3 >= 3.0.13, PHP 4, PHP 5)

recode_string -- Recode a string according to a recode request

Description

string recode_string ( string request, string string )

Recode the string string according to the recode request request. Returns the recoded string or FALSE, if unable to perform the recode request.

A simple recode request may be "lat1..iso646-de". See also the GNU Recode documentation of your installation for detailed instructions about recode requests.
Esempio 1. Basic recode_string() example:
<?php echo recode_string("us..flat", "The following character has a diacritical mark: á"); ?>

recode

(PHP 4, PHP 5)

recode -- Alias di recode_string()

Descrizione

This function is an alias of: recode_string().

CXXV. RPM Header Reading Funzioni

Introduzione

This module allows you to read the meta information stored in the headers of a RedHat Package Manager (RPM) file.

Requisiti

The RPMReader extension requires PHP 5.

Installazione

RPMReader is not bundled with PHP. It is a PECL extension and can be located here: http://pecl.php.net/package/rpmreader.

To enable extname support, configure PHP with --with-rpmreader

Tipi di risorse

There is one resource type used by the RPMReader module. The resource is a file pointer which identifies the RPM file with which to work.

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

The following list of constants are used to obtain information using the rpm_get_tag() function. These constants represent the tag number to be retrieved from the RPM file's header section. Descriptions are given below as to what data the tag number constants reference.

RPMREADER_MINIMUM (integer): The minimum valid value of any RPM tag number.
RPMREADER_NAME (integer): The name of the RPM package.
RPMREADER_VERSION (integer): The version of the RPM package.
RPMREADER_RELEASE (integer): The release of the RPM package.
RPMREADER_EPOCH (integer)
RPMREADER_SERIAL (integer)
RPMREADER_SUMMARY (integer): The summary text of the RPM package.
RPMREADER_DESCRIPTION (integer): The full description text of the RPM package.
RPMREADER_BUILDTIME (integer): The date and time when the RPM package was built.
RPMREADER_BUILDHOST (integer): The name of the host on which the RPM package was built.
RPMREADER_INSTALLTIME (integer)
RPMREADER_SIZE (integer): The size of the RPM package.
RPMREADER_DISTRIBUTION (integer)
RPMREADER_VENDOR (integer)
RPMREADER_GIF (integer)
RPMREADER_XPM (integer)
RPMREADER_LICENSE (integer)
RPMREADER_COPYRIGHT (integer)
RPMREADER_PACKAGER (integer)
RPMREADER_GROUP (integer)
RPMREADER_SOURCE (integer)
RPMREADER_PATCH (integer)
RPMREADER_URL (integer)
RPMREADER_OS (integer)
RPMREADER_ARCH (integer)
RPMREADER_PREIN (integer)
RPMREADER_POSTIN (integer)
RPMREADER_PREUN (integer)
RPMREADER_POSTUN (integer)
RPMREADER_OLDFILENAMES (integer): The list of files in an RPM package (deprecated format). The correct way is now to use a combination of 3 tags (RPMREADER_BASENAMES, RPMREADER_DIRINDEXES, RPMREADER_DIRNAMES) in what RPM now calls "CompressedFileNames". This tag is still used in older RPM files that did not use the "CompressedFileNames" method and is maintained for backward compatibility.
RPMREADER_FILESIZES (integer)
RPMREADER_FILESTATES (integer)
RPMREADER_FILEMODES (integer)
RPMREADER_FILERDEVS (integer)
RPMREADER_FILEMTIMES (integer)
RPMREADER_FILEMD5S (integer)
RPMREADER_FILELINKTOS (integer)
RPMREADER_FILEFLAGS (integer)
RPMREADER_FILEUSERNAME (integer)
RPMREADER_FILEGROUPNAME (integer)
RPMREADER_ICON (integer)
RPMREADER_SOURCERPM (integer)
RPMREADER_FILEVERIFYFLAGS (integer)
RPMREADER_ARCHIVESIZE (integer)
RPMREADER_PROVIDENAME (integer)
RPMREADER_PROVIDES (integer)
RPMREADER_REQUIREFLAGS (integer)
RPMREADER_REQUIRENAME (integer)
RPMREADER_REQUIREVERSION (integer)
RPMREADER_CONFLICTFLAGS (integer)
RPMREADER_CONFLICTNAME (integer)
RPMREADER_CONFLICTVERSION (integer)
RPMREADER_EXCLUDEARCH (integer)
RPMREADER_EXCLUDEOS (integer)
RPMREADER_EXCLUSIVEARCH (integer)
RPMREADER_EXCLUSIVEOS (integer)
RPMREADER_RPMVERSION (integer)
RPMREADER_TRIGGERSCRIPTS (integer)
RPMREADER_TRIGGERNAME (integer)
RPMREADER_TRIGGERVERSION (integer)
RPMREADER_TRIGGERFLAGS (integer)
RPMREADER_TRIGGERINDEX (integer)
RPMREADER_VERIFYSCRIPT (integer)
RPMREADER_CHANGELOGTIME (integer): The list of dates from changelog entries.
RPMREADER_CHANGELOGNAME (integer): The list of changelog entry names.
RPMREADER_CHANGELOGTEXT (integer): The list of the text from changelog entries.
RPMREADER_PREINPROG (integer)
RPMREADER_POSTINPROG (integer)
RPMREADER_PREUNPROG (integer)
RPMREADER_POSTUNPROG (integer)
RPMREADER_BUILDARCHS (integer)
RPMREADER_OBSOLETENAME (integer)
RPMREADER_OBSOLETES (integer)
RPMREADER_VERIFYSCRIPTPROG (integer)
RPMREADER_TRIGGERSCRIPTPROG (integer)
RPMREADER_COOKIE (integer)
RPMREADER_FILEDEVICES (integer)
RPMREADER_FILEINODES (integer)
RPMREADER_FILELANGS (integer)
RPMREADER_PREFIXES (integer)
RPMREADER_INSTPREFIXES (integer)
RPMREADER_PROVIDEFLAGS (integer)
RPMREADER_PROVIDEVERSION (integer)
RPMREADER_OBSOLETEFLAGS (integer)
RPMREADER_OBSOLETEVERSION (integer)
RPMREADER_DIRINDEXES (integer): The list of indices that relate directory names to files in the RPM package. This tag is used in conjunction with RPMREADER_BASENAMES and RPMREADER_DIRNAMES to reconstruct filenames in the RPM package stored with the new "CompressedFileNames" method in RPM.
RPMREADER_BASENAMES (integer): The list of the names of files in the RPM package without path information. This tag is used in conjunction with RPMREADER_DIRINDEXES and RPMREADER_DIRNAMES to reconstruct filenames in the RPM package stored with the new "CompressedFileNames" method in RPM.
RPMREADER_DIRNAMES (integer): The list of directory names used by files in the RPM package. This tag is used in conjunction with RPMREADER_BASENAMES and RPMREADER_DIRINDEXES to reconstruct filenames in the RPM package stored with the new "CompressedFileNames" method in RPM.
RPMREADER_OPTFLAGS (integer)
RPMREADER_DISTURL (integer)
RPMREADER_PAYLOADFORMAT (integer)
RPMREADER_PAYLOADCOMPRESSOR (integer)
RPMREADER_PAYLOADFLAGS (integer)
RPMREADER_INSTALLCOLOR (integer)
RPMREADER_INSTALLTID (integer)
RPMREADER_REMOVETID (integer)
RPMREADER_RHNPLATFORM (integer)
RPMREADER_PLATFORM (integer)
RPMREADER_PATCHESNAME (integer)
RPMREADER_PATCHESFLAGS (integer)
RPMREADER_PATCHESVERSION (integer)
RPMREADER_CACHECTIME (integer)
RPMREADER_CACHEPKGPATH (integer)
RPMREADER_CACHEPKGSIZE (integer)
RPMREADER_CACHEPKGMTIME (integer)
RPMREADER_FILECOLORS (integer)
RPMREADER_FILECLASS (integer)
RPMREADER_CLASSDICT (integer)
RPMREADER_FILEDEPENDSX (integer)
RPMREADER_FILEDEPENDSN (integer)
RPMREADER_DEPENDSDICT (integer)
RPMREADER_SOURCEPKGID (integer)
RPMREADER_FILECONTEXTS (integer)
RPMREADER_FSCONTEXTS (integer)
RPMREADER_RECONTEXTS (integer)
RPMREADER_POLICIES (integer)
RPMREADER_MAXIMUM (integer): The maximum valid value of any RPM tag number.

Esempi

This example will open an RPM file and read the name, version, and release from the RPM file, echo the results, and close the RPM file.

Esempio 1. Basic RPMReader Example

<?php

$filename = "/path/to/file.rpm";

// open file
$rpmr = rpm_open($filename);

// get "Name" tag
$name = rpm_get_tag($rpmr, RPMREADER_NAME);

// get "Version" tag
$ver = rpm_get_tag($rpmr, RPMREADER_VERSION);

// get "Release" tag
$rel = rpm_get_tag($rpmr, RPMREADER_RELEASE);

echo "$name-$ver-$rel<br>\n";

// close file
rpm_close($rpmr);

?>

Sommario
rpm_close -- Closes an RPM file
rpm_get_tag -- Retrieves a header tag from an RPM file
rpm_is_valid -- Tests a filename for validity as an RPM file
rpm_open -- Opens an RPM file

rpm_close

(no version information, might be only in CVS)

rpm_close -- Closes an RPM file

Descrizione

boolean rpm_close ( resource rpmr )

rpm_close() will close an RPM file pointer.

Elenco dei parametri

rpmr: A file pointer resource successfully opened by rpm_open().

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 1. rpm_close() example
<?php $file = "/path/to/file.rpm"; $rpmr = rpm_open($file); rpm_close($rpmr); ?>

Vedere anche:

rpm_open()

rpm_get_tag

(no version information, might be only in CVS)

rpm_get_tag -- Retrieves a header tag from an RPM file

Descrizione

mixed rpm_get_tag ( resource rpmr, int tagnum )

rpm_get_tag() will retrieve a given tag from the RPM file's header and return it.

Elenco dei parametri

rpmr: A file pointer resource successfully opened by rpm_open().
tagnum: The tag number to retrieve from the RPM header. This value can be specified using the list of constants defined by this module.

Valori restituiti

The return value can be of various types depending on the tagnum supplied to the function.

Esempi

Esempio 1. rpm_get_tag() example
<?php $file = "/path/to/file.rpm"; $rpmr = rpm_open($file); $name = rpm_get_tag($rpmr, RPMREADER_NAME); echo "$name<br>\n"; rpm_close($rpmr); ?>

Vedere anche:

rpm_open()

rpm_close()

rpm_is_valid

(no version information, might be only in CVS)

rpm_is_valid -- Tests a filename for validity as an RPM file

Descrizione

boolean rpm_is_valid ( string filename )

rpm_is_valid() will test an RPM file for validity as an RPM file. This is not the same as rpm_open() as it only checks the file for validity but does not return a file pointer to be used by further functions.

Elenco dei parametri

filename: The filename of the RPM file you wish to check for validity.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 1. rpm_is_valid() example
<?php $file = "/path/to/file.rpm"; if (rpm_is_valid($file)) { echo "File is recognized as an RPM file.<br>\n"; } else { echo "File is not recognized as an RPM file.<br>\n"; } ?>

rpm_open

(no version information, might be only in CVS)

rpm_open -- Opens an RPM file

Descrizione

resource rpm_open ( string filename )

rpm_open() will open an RPM file and will determine if the file is a valid RPM file.

Elenco dei parametri

filename: The filename of the RPM file you wish to open.

Valori restituiti

If the open succeeds, then rpm_open() will return a file pointer resource to the newly opened file. On error, the function will return FALSE.

Esempi

Esempio 1. rpm_open() example
<?php $file = "/path/to/file.rpm"; $rpmr = rpm_open($file); rpm_close($rpmr); ?>

Vedere anche:

rpm_close()

CXXVI. runkit Functions

Introduzione

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.

Additional information such as new releases, downloads, source files, maintainer information, and a CHANGELOG, can be located here: http://pecl.php.net/package/runkit.

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.

Requisiti

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.

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

Tabella 1. Runkit Configuration Options

Name	Default	Changeable	Changelog
runkit.superglobal		PHP_INI_PERDIR
runkit.internal_override		PHP_INI_SYSTEM

Per maggiori dettagli sulle costanti PHP_INI_* vedere Appendice G.

Breve descrizione dei parametri di configurazione.

runkit.superglobal string

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.

Esempio 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();
?>

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

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): PHP5 specific flag to runkit_method_add()
RUNKIT_ACC_PROTECTED (integer): PHP5 specific flag to runkit_method_add()
RUNKIT_ACC_PRIVATE (integer): PHP5 specific flag to runkit_method_add()
CLASSKIT_ACC_PUBLIC (integer): PHP5 specific flag to classkit_method_add() Only defined when classkit compatibility is enabled.
CLASSKIT_ACC_PROTECTED (integer): PHP5 specific flag to classkit_method_add() Only defined when classkit compatibility is enabled.
CLASSKIT_ACC_PRIVATE (integer): PHP5 specific flag to classkit_method_add() Only defined when classkit compatibility is enabled.
CLASSKIT_AGGREGATE_OVERRIDE (integer): PHP5 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.

Sommario
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_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

Runkit_Sandbox

(no version information, might be only in CVS)

Runkit_Sandbox -- Runkit Sandbox Class -- PHP Virtual Machine

Descrizione

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.

Nota: Sandbox support (required for runkit_lint(), runkit_lint_file(), and the Runkit_Sandbox class) is only available with PHP 5.1 or specially patched versions of PHP 5.0 and requires that thread safety be enabled. See the README file included in the runkit package for more information.

Constructor

void Runkit_Sandbox::__construct ( [array 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_basedir may 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 to FALSE when it is previously set to TRUE
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.

Esempio 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.

Esempio 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));');
?>

Il precedente esempio visualizzerà:

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().

Esempio 3. Calling sandbox functions

<?php
$sandbox = new Runkit_Sandbox();

echo $sandbox->str_replace('a','f','abc');
?>

Il precedente esempio visualizzerà:

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.

Esempio 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');
?>

Il precedente esempio visualizzerà:

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.

Tabella 1. Sandbox Settings / Status Indicators

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)

Runkit_Sandbox_Parent

(no version information, might be only in CVS)

Runkit_Sandbox_Parent -- Runkit Anti-Sandbox Class

Descrizione

void Runkit_Sandbox_Parent::__construct ( void )

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.

Nota: Sandbox support (required for runkit_lint(), runkit_lint_file(), and the Runkit_Sandbox class) is only available with PHP 5.1 or specially patched versions of PHP 5.0 and requires that thread safety be enabled. See the README file included in the runkit package for more information.

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.

Esempio 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.

Esempio 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);');
}
?>

Il precedente esempio visualizzerà:

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_class_adopt -- Convert a base class to an inherited class, add ancestral methods when appropriate

Descrizione

bool runkit_class_adopt ( string classname, string parentname )

Elenco dei parametri

classname: Name of class to be adopted
parentname: Parent class which child class is extending

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 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(); ?>
Il precedente esempio visualizzerà:
Parent Function Output

Vedere anche:

runkit_class_emancipate()

runkit_class_emancipate

(PECL)

runkit_class_emancipate -- Convert an inherited class to a base class, removes any method whose scope is ancestral

Descrizione

bool runkit_class_emancipate ( string classname )

Elenco dei parametri

classname: Name of class to emancipate

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 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(); ?>
Il precedente esempio visualizzerà:
Parent Function Output Fatal error: Call to undefined function: parentFunc() in example.php on line 12

Vedere anche:

runkit_class_adopt()

runkit_constant_add

(PECL)

runkit_constant_add -- Similar to define(), but allows defining in class definitions as well

Descrizione

bool runkit_constant_add ( string constname, mixed value )

Elenco dei parametri

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.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

define()

runkit_constant_redefine()

runkit_constant_remove()

runkit_constant_redefine

(PECL)

runkit_constant_redefine -- Redefine an already defined constant

Descrizione

bool runkit_constant_redefine ( string constname, mixed newvalue )

Elenco dei parametri

constname: Constant to redefine. Either string indicating global constant, or classname::constname indicating class constant.
newvalue: New value to assign to constant.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

runkit_constant_add()

runkit_constant_remove()

runkit_constant_remove

(PECL)

runkit_constant_remove -- Remove/Delete an already defined constant

Descrizione

bool runkit_constant_remove ( string constname )

Elenco dei parametri

constname: Name of constant to remove. Either a string indicating a global constant, or classname::constname indicating a class constant.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

define()

runkit_constant_add()

runkit_constant_redefine()

runkit_function_add

(PECL)

runkit_function_add -- Add a new function, similar to create_function()

Descrizione

bool runkit_function_add ( string funcname, string arglist, string code )

Elenco dei parametri

funcname: Name of function to be created
arglist: Comma separated argument list
code: Code making up the function

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 1. A runkit_function_add() example
<?php create_function('testme','$a,$b','echo "The value of a is $a\n"; echo "The value of b is $b\n";'); testme(1,2); ?>
Il precedente esempio visualizzerà:
The value of a is 1 The value of b is 2

Vedere anche:

create_function()

runkit_function_redefine()

runkit_function_copy()

runkit_function_rename()

runkit_function_remove()

runkit_function_copy

(PECL)

runkit_function_copy -- Copy a function to a new function name

Descrizione

bool runkit_function_copy ( string funcname, string targetname )

Elenco dei parametri

funcname: Name of existing function
targetname: Name of new function to copy definition to

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 1. A runkit_function_copy() example
<?php function original() { echo "In a function\n"; } runkit_function_copy('original','duplicate'); original(); duplicate(); ?>
Il precedente esempio visualizzerà:
In a function In a function

Vedere anche:

runkit_function_add()

runkit_function_redefine()

runkit_function_rename()

runkit_function_remove()

runkit_function_redefine

(PECL)

runkit_function_redefine -- Replace a function definition with a new implementation

Descrizione

bool runkit_function_redefine ( string funcname, string arglist, string code )

Elenco dei parametri

funcname: Name of function to redefine
arglist: New list of arguments to be accepted by function
code: New code implementation

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.

Elenco dei parametri

filename: Filename to import function and class definitions from
flags: Bitwise OR of the RUNKIT_IMPORT_* family of constants.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

runkit_lint_file

(PECL)

runkit_lint_file -- Check the PHP syntax of the specified file

Descrizione

bool runkit_lint_file ( string 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.

Nota: Sandbox support (required for runkit_lint(), runkit_lint_file(), and the Runkit_Sandbox class) is only available with PHP 5.1 or specially patched versions of PHP 5.0 and requires that thread safety be enabled. See the README file included in the runkit package for more information.

Elenco dei parametri

filename: File containing PHP Code to be lint checked

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

runkit_lint()

runkit_lint

(PECL)

runkit_lint -- Check the PHP syntax of the specified php code

Descrizione

bool runkit_lint ( string 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 commandline except runkit_lint() accepts actual code rather than a filename.

Nota: Sandbox support (required for runkit_lint(), runkit_lint_file(), and the Runkit_Sandbox class) is only available with PHP 5.1 or specially patched versions of PHP 5.0 and requires that thread safety be enabled. See the README file included in the runkit package for more information.

Elenco dei parametri

code: PHP Code to be lint checked

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

runkit_lint_file()

runkit_method_add

(PECL)

runkit_method_add -- Dynamically adds a new method to a given class

Descrizione

bool runkit_method_add ( string classname, string methodname, string args, string code [, int flags] )

Avvertimento

Elenco dei parametri

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 methodname is called
flags: The type of method to create, can be RUNKIT_ACC_PUBLIC, RUNKIT_ACC_PROTECTED or RUNKIT_ACC_PRIVATE
Nota: This parameter is only used as of PHP 5, because, prior to this, all methods were public.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 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); ?>
Il precedente esempio visualizzerà:
16

Vedere anche:

runkit_function_add()

runkit_method_copy

(PECL)

runkit_method_copy -- Copies a method from class to another

Descrizione

bool runkit_method_copy ( string dClass, string dMethod, string sClass [, string sMethod] )

Avvertimento

Elenco dei parametri

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 dMethod is assumed.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 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(); ?>
Il precedente esempio visualizzerà:
foo!

Vedere anche:

runkit_function_copy()

runkit_method_redefine

(PECL)

runkit_method_redefine -- Dynamically changes the code of the given method

Descrizione

bool runkit_method_redefine ( string classname, string methodname, string args, string code [, int flags] )

Nota: This function cannot be used to manipulate the currently running (or chained) method.

Avvertimento

Elenco dei parametri

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 methodname is called
flags: The redefined method can be RUNKIT_ACC_PUBLIC, RUNKIT_ACC_PROTECTED or RUNKIT_ACC_PRIVATE
Nota: This parameter is only used as of PHP 5, because, prior to this, all methods were public.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 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(); ?>
Il precedente esempio visualizzerà:
Before: foo! After: bar!

Vedere anche:

runkit_function_redefine()

runkit_method_remove

(PECL)

runkit_method_remove -- Dynamically removes the given method

Descrizione

bool runkit_method_remove ( string classname, string methodname )

Nota: This function cannot be used to manipulate the currently running (or chained) method.

Avvertimento

Elenco dei parametri

classname: The class in which to remove the method
methodname: The name of the method to remove

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 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')); ?>
Il precedente esempio visualizzerà:
bar

Vedere anche:

runkit_function_remove()

runkit_method_rename

(PECL)

runkit_method_rename -- Dynamically changes the name of the given method

Descrizione

bool runkit_method_rename ( string classname, string methodname, string newname )

Nota: This function cannot be used to manipulate the currently running (or chained) method.

Avvertimento

Elenco dei parametri

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

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 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(); ?>
Il precedente esempio visualizzerà:
foo!

Vedere anche:

runkit_function_rename()

runkit_sandbox_output_handler

(PECL)

runkit_sandbox_output_handler -- Specify a function to capture and/or process output from a runkit sandbox

Descrizione

mixed runkit_sandbox_output_handler ( object sandbox [, mixed callback] )

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.

Nota: Sandbox support (required for runkit_lint(), runkit_lint_file(), and the Runkit_Sandbox class) is only available with PHP 5.1 or specially patched versions of PHP 5.0 and requires that thread safety be enabled. See the README file included in the runkit package for more information.

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.

Elenco dei parametri

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 sandbox will 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.

Valori restituiti

Returns the name of the previously defined output handler callback, or FALSE if no handler was previously defined.

Esempi

Esempio 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; ?>
Il precedente esempio visualizzerà:
Sandbox Complete Hello string(9) "Excuse me" I lost myself.

runkit_superglobals

(PECL)

runkit_superglobals -- Return numerically indexed array of registered superglobals

Descrizione

array runkit_superglobals ( void )

Valori restituiti

Returns a numerically indexed array of the currently registered superglobals. i.e. _GET, _POST, _REQUEST, _COOKIE, _SESSION, _SERVER, _ENV, _FILES

Vedere anche:

Variable Scope

CXXVII. Satellite CORBA client extension [deprecated]

Introduzione

Avvertimento

Nota: Questo modulo non è disponibile su piattaforme Windows.

Satellite is deprecated. It is suggested that you use Universe (http://universe-phpext.sourceforge.net/) and not Satellite.

The Satellite extension is used for accessing CORBA objects. You will need to set the idl_directory= entry in php.ini to a path where you store all IDL files you use.

See the Satellite README file for details about installing Satellite.

Sommario
OrbitEnum -- Use CORBA enums
OrbitObject -- Access CORBA objects
OrbitStruct -- Use CORBA structs
satellite_caught_exception -- See if an exception was caught from the previous function
satellite_exception_id -- Get the repository id for the latest exception.
satellite_exception_value -- Get the exception struct for the latest exception
satellite_get_repository_id -- NOT IMPLEMENTED
satellite_load_idl -- Instruct the type manager to load an IDL file
satellite_object_to_string -- Convert an object to its string representation

OrbitEnum

(no version information, might be only in CVS)

OrbitEnum -- Use CORBA enums

Descrizione

new OrbitEnum ( string id )

Avvertimento

This class represents the enumeration identified with the id parameter.

Elenco dei parametri

id: Can be either the name of the enumeration (e.g "MyEnum"), or the full repository id (e.g. "IDL:MyEnum:1.0").

Esempi

Esempio 1. Sample IDL file
enum MyEnum { a,b,c,d,e };

Esempio 2. PHP code for accessing MyEnum
<?php $enum = new OrbitEnum ("MyEnum"); echo $enum->a; /* write 0 */ echo $enum->c; /* write 2 */ echo $enum->e; /* write 4 */ ?>

OrbitObject

(no version information, might be only in CVS)

OrbitObject -- Access CORBA objects

Descrizione

new OrbitObject ( string ior )

Avvertimento

This class provides access to a CORBA object.

Elenco dei parametri

ior: Should be a string containing the IOR (Interoperable Object Reference) that identifies the remote object.

Esempi

Esempio 1. Sample IDL file
interface MyInterface { void SetInfo (string info); string GetInfo(); attribute int value; }

Esempio 2. PHP code for accessing MyInterface
<?php $obj = new OrbitObject ($ior); $obj->SetInfo ("A 2GooD object"); echo $obj->GetInfo(); $obj->value = 42; echo $obj->value; ?>

OrbitStruct

(no version information, might be only in CVS)

OrbitStruct -- Use CORBA structs

Descrizione

new OrbitStruct ( string id )

Avvertimento

This class represents the structure identified with the id parameter.

Elenco dei parametri

id: Can be either the name of the struct (e.g "MyStruct"), or the full repository id (e.g. "IDL:MyStruct:1.0").

Esempi

Esempio 1. Sample IDL file
struct MyStruct { short shortvalue; string stringvalue; }; interface SomeInterface { void SetValues (MyStruct values); MyStruct GetValues(); }

Esempio 2. PHP code for accessing MyStruct
<?php $obj = new OrbitObject ($ior); $initial_values = new OrbitStruct ("IDL:MyStruct:1.0"); $initial_values->shortvalue = 42; $initial_values->stringvalue = "HGTTG"; $obj->SetValues ($initial_values); $values = $obj->GetValues(); echo $values->shortvalue; echo $values->stringvalue; ?>

satellite_caught_exception

(4.0.3 - 4.1.2 only, PECL)

satellite_caught_exception -- See if an exception was caught from the previous function

Descrizione

bool satellite_caught_exception ( void )

Avvertimento

Valori restituiti

This function returns TRUE if an exception has been caught, FALSE otherwise.

Esempi

Esempio 1. Sample IDL file
/* ++?????++ Out of Cheese Error. Redo From Start. */ exception OutOfCheeseError { int parameter; } interface AnotherInterface { void AskWhy() raises (OutOfCheeseError); }

Esempio 2. PHP code for handling CORBA exceptions
<?php $obj = new OrbitObject ($ior); $obj->AskWhy(); if (satellite_caught_exception()) { if ("IDL:OutOfCheeseError:1.0" == satellite_exception_id()) { $exception = satellite_exception_value(); echo $exception->parameter; } } ?>

satellite_exception_id

(4.0.3 - 4.1.2 only, PECL)

satellite_exception_id -- Get the repository id for the latest exception.

Descrizione

string satellite_exception_id ( void )

Avvertimento

For example usage see satellite_caught_exception().

Valori restituiti

Return a repository id string. (E.g. "IDL:MyException:1.0".)

satellite_exception_value

(4.0.3 - 4.1.2 only, PECL)

satellite_exception_value -- Get the exception struct for the latest exception

Descrizione

OrbitStruct satellite_exception_value ( void )

string satellite_object_to_string ( object obj )

Convert an object to its string representation (IOR).

CXXVIII. SDO Functions

Introduzione

Avvertimento

Service Data Objects (SDOs) enable PHP applications to work with data from different sources (like a database query, an XML file, and a spreadsheet) using a single interface.

Each different kind of data source requires a Data Access Service (DAS) to provide access to the data in the data source. In your PHP application, you use a DAS to create an SDO instance that represents some data in the data source. You can then set and get values in the SDO instance using the standard SDO interface. Finally, you use a DAS to write the modified data back to a data source (typically the same one).

See the list of Data Access Services for details on those currently available. In addition to the provided DASs, SDO also provides interfaces to enable others to be implemented (see the section on SDO Data Access Services Interface for more details).

This extension is derived from concepts taken from the Service Data Objects specification

The Structure of a Service Data Object

A Service Data Object instance is made up of a tree of data objects. The tree is defined by containment references between the data objects. For example, a Company data object might consist of a number of Department data objects and therefore the Company would have a containment reference to the Departments. Deleting a data object which has a containment reference to another data object will delete the referenced data object. For example, deleting the Company data object will also delete the Departments.

An SDO may also have non-containment references between data objects in the tree. For example, one Employee data object might reference another Employee to identify a career mentor. Deleting a data object which has a non-containment reference to another data object does not delete the referenced data object.

As well as data objects referencing each other, they can also have primitive properties. For example, the Company data object might have a property called "name" of type string, for holding the name of the company (for example, "Acme").

Requisiti

The SDO extension requires PHP 5.1 or higher.

SDO XML Data Access Service, which is built as part of this extension, requires libxml2 (Tested with libxml2 2.6.19) which can be downloaded from http://www.xmlsoft.org/.

Installazione

There are several options, depending on whether you are installing on Windows or Linux, and depending on whether you are installing a released version (a .tgz file from the PECL site) or the latest from CVS. The Relational DAS also needs special attention as it is written in PHP.

The instructions are likely to change as PHP 5.1 progresses in status from beta to stable release. The instructions here were correct on 6th October 2005, when PHP 5.1.0RC1 was the current release candidate for PHP, and 0.5.2 was the current beta release of SDO.

The options are summarised in the following table:

latest/Release

Windows

Linux

latest CVS

The latest DLLs for the SDO core and the XML DAS can be downloaded from php_sdo and php_sdo_das_xml respectively.
Check out the Relational DAS from CVS to somewhere on the PHP include_path .

Check out the SDO core and the XML DAS from CVS and build according to the instructions below for building on Linux.
Check out the Relational DAS from CVS to somewhere on the PHP include_path .

Release

There is currently no way provided for building the release version of the SDO core and XML DAS on a user's machine. You will only be able to pick up the latest DLLs from the snaps site (see previous row of this table).
The Relational DAS can be downloaded and installed with the command:
pear install -B <package name and level>
Substitute the desired package name and level, for example sdo-0.5.2, in the command above.

You can download and install all three SDO components - the SDO core, the XML DAS and the Relational DAS - with the command:
pear install <package name and level>
Substitute the desired package name and level, for example sdo-0.5.2, in the command above.
This command will build the SDO and XML shared libraries as well as installing the PHP files that make the Relational DAS.

Regardless of which platform or which level of the code you have installed you will need add the two extension libraries to your php.ini file. On Windows, add:
extension=php_sdo.dll extension=php_sdo_das_xml.dll
On Linux, add:
extension=sdo.so extension=sdo_das_xml.so
You may also need to update your extension_dir in php.ini to point to the location of these libraries.

The Relational DAS is written in PHP. You may need to update your include_path in php.ini to point to the directory that contains sdo/DAS/Relational .

Building SDO on Linux

This section describes how to build the SDO core and XML DAS on Linux. Currently you would only need to know how to do this if you wish to build a recent version that you have checked out of CVS.

Change to the main extension directory: cd < wherever your sdo code is >
Run phpize, which will set up the environment to compile both SDO and the XML Data Access Service.
Next, run ./configure; make; make install. Please note, you may need to login as root to install the extension.
Make sure that these modules are loaded by PHP, by adding extension=sdo.so and extension=sdo_das_xml.so to your php.ini file in the same order.

Data Access Services

The table below lists the currently provided SDO Data Access Services:

DAS Name	Description
SDO_DAS_XML	An XML Data Access Service supporting reading/writing SDOs as XML documents or via a Web URL to supporting things like RSS feeds.
SDO_DAS_Relational	A PDO-based Data Access Service supporting reading/writing SDO to relational data sources. Implements an optimistic concurrency policy for updates.

Limitations

Implementation Limitations

The following are limitations in the current SDO implementation:

There is no support for multi-byte character sets.

SDO Limitations

The following SDO 2.0 concepts are not supported in the current PHP implementation. It is not necessarily the case that these will all be added over time. Their inclusion will depend on community requirements.

Abstract types and type derivation.
Open types.
Bi-directional relationships.
Type and property alias names.
Read-only properties.
Model introspection.
XMLHelper/XSDHelper (the XML DAS provide a lot of this functionality)
TypeHelper (the SDO_DAS_DataFactory provides this functionality)

Esempi

The examples below assume an SDO created with the schema and instance information shown below, using the XML Data Access Service.

The schema describes a company data object. The company contains department data objects, and each department contains employee data objects. Each data object has a number of primitive properties to describe things like name, serial number, etc. Finally, the company data object also has a non-containment reference to one of the employee data objects to identify them as the 'employeeOfTheMonth'.

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:sdo="commonj.sdo" xmlns:sdoxml="commonj.sdo/xml" xmlns:company="companyNS" targetNamespace="companyNS"> <xsd:element name="company" type="company:CompanyType"/> <xsd:complexType name="CompanyType"> <xsd:sequence> <xsd:element name="departments" type="company:DepartmentType" maxOccurs="unbounded"/> </xsd:sequence> <xsd:attribute name="name" type="xsd:string"/> <xsd:attribute name="employeeOfTheMonth" type="xsd:IDREF" sdoxml:propertyType="company:EmployeeType"/> </xsd:complexType> <xsd:complexType name="DepartmentType"> <xsd:sequence> <xsd:element name="employees" type="company:EmployeeType" maxOccurs="unbounded"/> </xsd:sequence> <xsd:attribute name="name" type="xsd:string"/> <xsd:attribute name="location" type="xsd:string"/> <xsd:attribute name="number" type="xsd:int"/> </xsd:complexType> <xsd:complexType name="EmployeeType"> <xsd:attribute name="name" type="xsd:string"/> <xsd:attribute name="SN" type="xsd:ID"/> <xsd:attribute name="manager" type="xsd:boolean"/> </xsd:complexType> </xsd:schema>

The instance document below describes a single company, called 'MegaCorp', which contains a single department, called 'Advanced Technologies'. The Advanced Technologies department contains three employees. The company employeeOfTheMonth is referencing the second employee, 'Jane Doe'.

<?xml version="1.0" encoding="UTF-8" ?> <company xmlns="companyNS" name="MegaCorp" employeeOfTheMonth="#/departments.0/employees.1"> <departments name="Advanced Technologies" location="NY" number="123"> <employees name="John Jones" SN="E0001"/> <employees name="Jane Doe" SN="E0003"/> <employees name="Al Smith" SN="E0004" manager="true"/> </departments> </company>

Setting and Getting Property Values

The following examples assume $company is a data object created from the schema and instance document shown above.

Esempio 1. Access via Property names
Data object properties can be accessed using the object property access syntax. The following gets the list of departments (containing a single department), and sets the company name to 'Acme'.
<?php $departments = $company->departments; $company->name = 'Acme'; ?>

Esempio 2. Access via Property index
Data object properties can be accessed via their property index using array syntax. The property index is the position at which the property's definition appears in the model (in this case the xml schema). We can see from the schema listing above that the departments element is the first company property defined and the company name attribute is the second company property (the SDO interface makes no distinction between XML attributes and elements). The following gets the list of departments (containing a single department), and sets the company name to 'Acme'.
<?php $departments = $company[0]; $company[1] = 'Acme'; ?>

Esempio 3. Data Object Iteration
We can iterate over the properties of a data object using foreach. The following iterates over the company properties; name, departments and employeeOfTheMonth.
<?php foreach ($company as $name => $value) { ... } ?>
For the first iteration, $name will be 'name' and $value will be 'Acme'. For the second iteration, $name will be 'departments' and $value will be an SDO_List (because departments is a many-valued property (stated maxOccurs="unbouded" in the schema)) containing a single data object of type DepartmentType. For the third iteration, $name will be 'employeeOfTheMonth' and $value will be a data object of type EmployeeType.

Esempio 4. Many-valued Property Iteration
Many-valued properties can also be iterated over using foreach. The following iterates over the company's departments.
<?php foreach ($company->departments as $department) { ... } ?>
Each iteration will assign the next department in the list to the variable $department.

Esempio 5. Many-valued Element Access
We can access individual elements of many-valued properties using array syntax. The following accesses the first department in the company.
<?php $ad_tech_dept = $company->departments[0]; ?>

Esempio 6. Nested Property Access
We can use nested property access to navigate the data object instance structure. The following gets and sets the name of the first department.
<?php $dept_name = $company->departments[0]->name; $company->departments[0]->name = 'Emerging Technologies'; ?>

Esempio 7. Simple XPath support
We can access properties using XPath-like (an augmented sub-set of XPath) expressions, the simplest form of which is the property name. The following sets the company name and gets the employeeOfTheMonth.
<?php $company['name'] = 'UltraCorp'; $eotm = $company['employeeOfTheMonth']; ?>

Esempio 8. Simple XPath support
We can use chained array access calls to navigate the data object instance structure. The following gets and sets the name of the first department.
<?php $dept_name = $company['departments'][0]['name']; $company['departments'][0]['name'] = 'Emerging Technologies'; ?>

Esempio 9. XPath Navigation
We can use XPath expressions to navigate the data object instance structure. Two forms of indexing into many-valued properties are supported. The first is the standard XPath array syntax with the indexing starting at one, the second is an SDO extension to XPath with an index starting at zero. The following both get the second employee from the first department.
<?php $jane_doe = $company["departments[1]/employees[2]"]; $jane_doe = $company["departments.0/employees.1"]; ?>

Esempio 10. XPath Querying
We can use XPath to query and identify parts of a data object based on instance data. The following retrieves the manager from the 'Advanced Technologies' department.
<?php $ad_tech_mgr = $company["departments[name=\"Advanced Technologies\"]/employees[manager=\"true\"]"]; ?>

Esempio 11. Creating child data object
A data object can be a factory for its child data objects. A child data object is automatically part of the data graph. The following add a new employee to the 'Advanced Technologies' department.
<?php $ad_tech_dept = $company["departments[name=\"Advanced Technologoies\"]"]; $new_hire = $ad_tech_dept->createDataObject('employees'); $new_hire->name = 'John Johnson'; $new_hire->SN = 'E0005'; $new_hire->manager = false; ?>

Esempio 12. Unset referenced data object
We can use the isset() and unset() functions to test and remove items from the data object.
The following removes the 'employeeOfTheMonth' from the company. If this were a containment reference then the employee would be removed from the company (probably not a good idea to sack your best employee each month!), but since this is a non-containment reference, the employee being referenced will remain in the department in the company, but will no longer be accessible via the employeeOfTheMonth property.
<?php if (isset($company->employeeOfTheMonth)) { unset($company->employeeOfTheMonth); } ?>

Working with Sequenced Data Objects

Sequenced data objects are SDOs which can track property ordering across the properties of a data object. They can also contain unstructured text elements (text element which do not belong to any of the SDO's properties). Sequenced data objects are useful for working with XML documents which allow unstructured text (i.e. mixed=true) or if the elements can be interleaved ( <A/><B/><A/>). This can occur for example when the schema defines maxOccurs>1 on a element which is a complexType with a choice order indicator.

The examples below assume an SDO created with the following schema and instance information, using the XML Data Access Service.

The schema below describes the format of a letter. The letter can optionally contain three properties; date, firstName, and lastName. The schema states mixed="true" which means that unstructured text can be interspersed between the three properties.

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:letter="http://letterSchema" targetNamespace="http://letterSchema"> <xsd:element name="letters" type="letter:FormLetter"/> <xsd:complexType name="FormLetter" mixed="true"> <xsd:sequence> <xsd:element name="date" minOccurs="0" type="xsd:string"/> <xsd:element name="firstName" minOccurs="0" type="xsd:string"/> <xsd:element name="lastName" minOccurs="0" type="xsd:string"/> </xsd:sequence> </xsd:complexType> </xsd:schema>

The following is an instance letter document. It contains the three letter properties; date, firstName and lastName, and has unstructured text elements for the address and letter body.

<letter:letters xmlns:letter="http://letterSchema"> <date>March 1, 2005</date> Mutual of Omaha Wild Kingdom, USA Dear <firstName>Casy</firstName> <lastName>Crocodile</lastName> Please buy more shark repellent. Your premium is past due. </letter:letters>

When loaded, the letter data object will have the sequence and property indices shown in the table below:

Sequence Index	Property Index:Name	Value
0	0:date	March 1, 2005
1	-	Mutual of Omaha
2	-	Wild Kingdom, USA
3	-	Dear
4	1:firstName	Casy
5	2:lastName	Crocodile
6	-	Please buy more shark repellent.
7	-	Your premium is past due.

To ensure sequence indices are maintained, sequenced data objects should be manipulated through the SDO_Sequence interface. This allows the data object's instance data to be manipulated in terms of the sequence index as opposed to the property index (shown in the table above). The following examples assume the letter instance has been loaded into a data object referenced by the variable $letter.
Esempio 13. Getting the SDO_Sequence interface
We obtain a data object's sequence using the getSequence() method. The follow gets the sequence for the letter data object.
<?php $letter_seq = $letter->getSequence(); ?>

All subsequent examples assume that the $letter_seq variable has been assigned the sequence for the letter data object.

Esempio 14. Get/set sequence values
We can get and set individual values (including unstructured text) using the sequence index. The following sets the firstName to 'Snappy' and gets the last sequence values (the unstructured text, 'Your premium is past due.').
<?php $letter_seq[4] = 'Snappy'; $text = $letter_seq[count($letter_seq) - 1]; ?>

Esempio 15. Sequence iteration
We can iterate through the individual sequence values using foreach. The following runs through the individual values in sequence order.
<?php foreach ($letter->getSequence() as $value) { ... } ?>

Esempio 16. Sequence versus Data Object
Setting values through the data object interface may result in the value not being part of the sequence. A value set through the data object will only be accessible through the sequence if the property was already part of the sequence. The following example sets the lastName through the data object and gets it through the sequence. This is fine because lastName already exists in the sequence. If it had not previously been set, then lastName would be set to 'Smith', but would not be part of the sequence.
<?php $letter[2] = 'Smith'; $last_name = $letter_seq[5]; ?>

Esempio 17. Adding to a sequence
We can add new values to a sequence using the SDO_Sequence::insert() method. The following examples assume that the 'firstName' and 'lastName' properties are initially unset.
<?php // Append a firstName value to the sequence // value: 'Smith' // sequence index: NULL (append) // propertyIdentifier: 1 (firtName property index) $letters_seq->insert('Smith', NULL, 1); // Append a lastName value to the sequence // value: 'Jones' // sequence index: NULL (append) // property identifier: 'lastName' (lastName property name) $letters_seq->insert('Jones', NULL, 'lastName'); // Append unstructured text // value: 'Cancel Subscription.' // sequence index: absent (append) // propertyIdentifier: absent (unstructured text) $letters_seq->insert('Cancel Subscription.'); // Insert new unstructured text. Subsequent sequence values // are shifted up. // value: 'Care of:' // sequence index: 1 (insert as second element) // propertyIdentifier: absent (unstructured text) $letters_seq->insert('Care of:', 1); ?>

Esempio 18. Removing from a sequence
We can use the isset() and unset() functions to test and remove items from the sequence (Note: unset() currently leaves the values in the data object, but this behaviour is likely to change to also remove the data from the data object). A sequence behaves like a contiguous list; therefore, removing items from the middle will shift entries at higher indices down. The following example tests to see if the first sequence element is set and unsets it if is.
<?php if (isset($letter_seq[0]) { unset($letter_seq[0]); } ?>

Classi predefinite

SDO consists of two sets of interfaces. The first set covers those interfaces for use by SDO client applications. These are identified by the package prefix 'SDO_'. The second set is those for use by Data Access Service implementations and are identified by the package prefix 'SDO_DAS_'. The majority of SDO users will not need to use or understand the 'SDO_DAS_' interfaces.

SDO Application Programmer Interface

SDO_DataObject

The main interface through which data objects are manipulated. In addition to the methods below, SDO_DataObject extends the ArrayAccess, SDO_PropertyAccess (defines __get() / __set() methods for property access overloading), Iterator, and Countable interfaces.

Metodi

getType - get the type of a data object
getSequence - get the sequence for the data object
createDataObject - create a child data object
clear - unset the properties of a data object
getContainer - get the container (also known as 'parent') of this data object
getContainmentPropertyName - get the name by which the parent refers to this data object

SDO_Sequence

The interface through which sequenced data objects can be accessed to preserve ordering across a data object's properties and to allow unstructured text. SDO_Sequence preserves contiguous indices and therefore inserting or removing elements may shift other elements up or down. In addition to the methods below, SDO_Sequence extends the ArrayAccess, Iterator and Countable interface.

Metodi

getPropertyIndex - get the property index for a given sequence index
getPropertyName - get the property name for a given sequence index
move - move an element from one property index to another
insert - insert a new value into the sequence

SDO_List

The interface through which many-valued properties are manipulated. In addition to the method defined below, SDO_List extends ArrayAccess, Iterator and Countable. SDO_List preserves contiguous indices and therefore inserting or removing elements may shift other elements up or down.

Metodi

insert - insert a new value into the list

SDO_DataFactory

The interface through which data objects can be created. A Data Access Service is responsible for populating the model (i.e. configuring the data factory with the type and structure information for the data objects it can create.) for the factory and can then optionally return an instance of, or implement, the SDO_DataFactory interface.

Metodi

create - create a new data object

SDO Data Access Service Developer Interfaces

SDO_DAS_DataObject

The interface through which a Data Access Service can access a data object's SDO_DAS_ChangeSummary . The change summary is used by the Data Access Service to check for conflicts when applying changes back to a data source.

Metodi

getChangeSummary - get the change summary for a data object

SDO_DAS_ChangeSummary

The interface through which the change history of a data object is accessed. The change summary holds information for any modifications on a data object which occurred since logging was activated. In the case of deletions and modifications, the old values are also held in the change summary.

If logging is no longer active then the change summary only holds changes made up to the point when logging was deactivated. Reactivating logging clears the change summary. This is useful when a set of changes have been written out by a DAS and the data object is to be reused.

Metodi

beginLogging - begin logging changes made to a data object
endLogging - end logging changes made to a data object
isLogging - test to see if change logging is on
getChangedDataObjects - get a list of the data objects which have been changed
getChangeType - get the type of change which has been made to a data object
getOldValues - get a list of old values for a data object
getOldContainer - get the old container data object for a deleted data object

SDO_DAS_Setting

The interface through which the old value for a property is accessed. A list of settings is returned by the change summary method getOldValues() .

Metodi

getPropertyIndex - get the property index for the changed property
getPropertyName - get the property name for the changed property
getValue - get the old value for the changed property
getListIndex - get the list index for the old value if it was part of a many-valued property
isSet - test to see if the property was set prior to being modified

SDO_DAS_DataFactory

The interface for constructing the model for an SDO_DataObject. The SDO_DAS_DataFactory is an abstract class providing a static method which returns a concrete data factory implementation. The implementation is used by Data Access Services to create an SDO model from their model. For example, a Relational Data Access Service might create and populate an SDO_DAS_DataFactory model based on a schema for a relational database.

Metodi

getDataFactory - static methods for getting a concrete data factory instance

addType - add a new type to the SDO model

addPropertyToType - add a new property to a type definition in the SDO model

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

SDO_DAS_ChangeSummary::NONE=0 (integer): Represents a change type of 'none'.
SDO_DAS_ChangeSummary::MODIFICATION=1 (integer): Represents a change type of 'modification'.
SDO_DAS_ChangeSummary::ADDITION=2 (integer): Represents a change type of 'addition'.
SDO_DAS_ChangeSummary::DELETION=3 (integer): Represents a change type of 'deletion'.

Sommario
SDO_DAS_ChangeSummary::beginLogging -- Begin change logging.
SDO_DAS_ChangeSummary::endLogging -- End change logging.
SDO_DAS_ChangeSummary::getChangeType -- Get the type of change made to an SDO_DataObject.
SDO_DAS_ChangeSummary::getChangedDataObjects -- Get the changed data objects from a change summary.
SDO_DAS_ChangeSummary::getOldContainer -- Get the old container for a deleted SDO_DataObject.
SDO_DAS_ChangeSummary::getOldValues -- Get the old values for a given changed SDO_DataObject.
SDO_DAS_ChangeSummary::isLogging -- Test to see whether change logging is switched on.
SDO_DAS_DataFactory::addPropertyToType -- Adds a property to a type.
SDO_DAS_DataFactory::addType -- Add a new type to a model.
SDO_DAS_DataFactory::getDataFactory -- Get a data factory instance.
SDO_DAS_DataObject::getChangeSummary -- Get a data object's change summary.
SDO_DAS_Setting::getListIndex -- Get the list index for a changed many-valued property.
SDO_DAS_Setting::getPropertyIndex -- Get the property index for a changed property.
SDO_DAS_Setting::getPropertyName -- Get the property name for a changed property.
SDO_DAS_Setting::getValue -- Get the old value for the changed property.
SDO_DAS_Setting::isSet -- Test whether a property was set prior to being modified.
SDO_DataFactory::create -- Create an SDO_DataObject.
SDO_DataObject::clear -- Clear an SDO_DataObject's properties.
SDO_DataObject::createDataObject -- Create a child SDO_DataObject.
SDO_DataObject::getContainer -- Get a data object's container.
SDO_DataObject::getContainmentPropertyName -- Get the container's property name.
SDO_DataObject::getSequence -- Get the sequence for a data object.
SDO_DataObject::getType -- Get the type of a data object.
SDO_List::insert -- Insert into a list.
SDO_Sequence::getPropertyIndex -- Return the property index for the specified sequence index.
SDO_Sequence::getPropertyName -- Return the property name for the specified sequence index.
SDO_Sequence::insert -- Insert into a sequence.
SDO_Sequence::move -- Move an item to another sequence position.

SDO_DAS_ChangeSummary::NONE
SDO_DAS_ChangeSummary::MODIFICATION
SDO_DAS_ChangeSummary::ADDITION
SDO_DAS_ChangeSummary::DELETION

The type name for the parent type.

propertyName

The name by which the property will be known in the parent type.

propertyNamespaceURI

The namespace URI for the type of the property.

propertyTypeName

The type name for the type of the property

options

This array holds one or more key=>value pairs to set attribute values for the property. The optional keywords are:

many: A flag to say whether the property is many-valued. A value of 'true' adds the property as a many-valued property (default is 'false').
readOnly: A flag to say whether the property is read-only. A value of 'true' means the property value cannot be modified through the SDO application APIs (default is 'false').
containment: A flag to say whether the property is contained by the parent. A value of 'true' means the property is contained by the parent. A value of 'false' results in a non-containment reference (default is 'true'). This flag is only interpreted when adding properties which are data object types, otherwise it is ignored.
default: A default value for the property. Omitting this key means that the property does not have a default value. A property can only have a default value if it is a single-valued data type (primitive).

Valori restituiti

None.

Log delle modifiche

Versione	Descrizione
0.5.2	Optional parameters `many`, `readOnly`, and `containment` deprecated in favour of the `options` array.

Esempi

Esempio 1. A SDO_DAS_DataFactory::addPropertyToType() example
The following adds an 'addressline' property to a Person type. The person type is identified by its namespace, 'PersonNS', and type name, 'PersonType'. The type of the 'addressline' property is a many-valued SDO data type (primitive) with namespace 'commonj.sdo' and type name 'String'.
<?php $df->addPropertyToType('PersonNS', 'PersonType', 'addressline', 'commonj.sdo', 'String', array('many'=>true)); ?>

SDO_DAS_DataFactory::addType

(no version information, might be only in CVS)

SDO_DAS_DataFactory::addType -- Add a new type to a model.

Descrizione

void SDO_DAS_DataFactory::addType ( string namespaceURI, string typeName )

Avvertimento

Add a new type to the SDO_DAS_DataFactory, defined by its namespace and type name. The type becomes part of the model of data objects that the data factory can create.

Elenco dei parametri

namespaceURI: The namespace of the type.
typeName: The name of the type.

Elenco dei parametri

namespaceURI: The namespace of the type.
typeName: The name of the type.

Valori restituiti

Returns the newly created SDO_DataObject.

Eccezioni

SDO_TypeNotFoundException: Thrown if the namespaceURI and typeName do not correspond to a type known to this data factory.

SDO_DataObject::clear

(no version information, might be only in CVS)

SDO_DataObject::clear -- Clear an SDO_DataObject's properties.

Descrizione

void SDO_DataObject::clear ( void )

Avvertimento

Clear an SDO_DataObject's properties. Read-only properties are unaffected. Subsequent calls to isset() for the data object will return FALSE.

Elenco dei parametri

None.

Valori restituiti

No return values.

SDO_DataObject::createDataObject

(no version information, might be only in CVS)

SDO_DataObject::createDataObject -- Create a child SDO_DataObject.

Descrizione

SDO_DataObject SDO_DataObject::createDataObject ( mixed identifier )

Avvertimento

Create a child SDO_DataObject of the default type for the property identified. The data object is automatically inserted into the tree and a reference to it is returned.

Elenco dei parametri

identifier: Identifies the property for the data object type to be created. Can be either a property name (string), or property index (int).

Valori restituiti

Returns the newly created SDO_DataObject.

Eccezioni

SDO_PropertyNotFoundException: Thrown if the identifier does not correspond to a property of the data object.

Esempi

Esempio 1. A SDO_DataObject::getType() example
For example, if the SDO_DataObject were of type 'CompanyType' from the namespace 'CompanyNS', then getType() would return the equivalent to array('CompanyNS', 'CompanyType'):
<?php $do_type = $company_do->getType(); echo "Namespace: $do_type[0], Type Name: $do_type[1]"; ?>
Il precedente esempio visualizzerà:
Namespace: CompanyNS, Type Name: CompanyType

SDO_List::insert

(no version information, might be only in CVS)

SDO_List::insert -- Insert into a list.

Descrizione

void SDO_List::insert ( mixed value [, int index] )

Avvertimento

Insert a new element at a specified position in the list. All subsequent list items are moved up.

Elenco dei parametri

value: The new value to be inserted. This can be either a primitive or an SDO_DataObject.
index: The position at which to insert the new element. If this argument is not specified then the new value will be appended.

Valori restituiti

None.

Eccezioni

SDO_IndexOutOfBoundsException: Thrown if the list index is less than zero or greater than the size of the list.
SDO_InvalidConversionException: Thrown if the type of the new value does not match the type for the list (e.g. the type of the many-valued property that the list represents).

SDO_Sequence::getPropertyIndex

(no version information, might be only in CVS)

SDO_Sequence::getPropertyIndex -- Return the property index for the specified sequence index.

Descrizione

int SDO_Sequence::getPropertyIndex ( int sequenceIndex )

Avvertimento

Return the property index for the specified sequence index. If the sequence item is unstructured text rather than a data object property, then a value of -1 is returned.

Elenco dei parametri

sequenceIndex: The sequence index for which we wish to determine the associated data object property index.

Valori restituiti

The corresponding property index. A value of -1 means the element does not belong to a property and must therefore be unstructured text.

Eccezioni

SDO_IndexOutOfBoundsException: Thrown if the sequence index is less than zero or greater than the size of the sequence.

SDO_Sequence::getPropertyName

(no version information, might be only in CVS)

SDO_Sequence::getPropertyName -- Return the property name for the specified sequence index.

Descrizione

string SDO_Sequence::getPropertyName ( int sequenceIndex )

Avvertimento

Return the property name for the specified sequence index. If the sequence item is unstructured text rather than a data object property, then a value of NULL is returned.

Elenco dei parametri

sequenceIndex: The sequence index for which we wish to determine the associated data object property name.

Valori restituiti

The corresponding property name. A value of NULL means the element does not belong to a property and must therefore be unstructured text.

Eccezioni

SDO_IndexOutOfBoundsException: Thrown if the sequence index is less than zero or greater than the size of the sequence.

SDO_Sequence::insert

(no version information, might be only in CVS)

SDO_Sequence::insert -- Insert into a sequence.

Descrizione

void SDO_Sequence::insert ( mixed value [, int sequenceIndex [, mixed propertyIdentifier]] )

Avvertimento

Insert a new element at a specified position in the sequence. All subsequent sequence items are moved up.

Elenco dei parametri

value: The new value to be inserted. This can be either a primitive or an SDO_DataObject.
sequenceIndex: The position at which to insert the new element. Default is NULL, which results in the new value being appended to the sequence.
propertyIdentifier: Either a property index or property name, used to identify a property in the sequence's corresponding SDO_DataObject. A value of NULL signifies unstructured text.

Valori restituiti

None.

Eccezioni

SDO_IndexOutOfBoundsException: Thrown if the sequence index is less than zero or greater than the size of the sequence.
SDO_InvalidConversionException: Thrown if the type of the new value cannot be juggled to match the type for the specified data object property.

SDO_Sequence::move

(no version information, might be only in CVS)

SDO_Sequence::move -- Move an item to another sequence position.

Descrizione

void SDO_Sequence::move ( int toIndex, int fromIndex )

Avvertimento

Modify the position of the item in the sequence, without altering the value of the property in the SDO_DataObject.

Elenco dei parametri

toIndex: The destination sequence index. If this index is less than zero or greater than the size of the sequence then the value is appended.
fromIndex: The source sequence index.

Valori restituiti

None.

Eccezioni

SDO_IndexOutOfBoundsException: Thrown if the fromIndex sequence index is less than zero or greater than the size of the sequence.

CXXIX. SDO XML Data Access Service Functions

Introduzione

Avvertimento

In order to use the XML Data Access Service for Service Data Objects, you will need to understand some of the concepts behind SDO: the data graph, the data object, XPath and property expressions, and so on. If you are not familiar with these ideas, you might want to look first at the section on SDO .

The job of the XML DAS is to move data between the application and an XML data source, which can be either a file or a URL. In order to do this it needs to be told the location of the XML schema, which is passed as a parameter to the create method of the XML DAS. The schema is used to ensure conformance of XML being written out, and also to ensure that modifications made to an SDO originating from XML follow the model described by the XML schema.

Requisiti

The SDO XML Data Access Service requires PHP 5.1 or higher. It is packaged with the SDO extension and requires SDO to have been installed. See the SDO installation instructions for the details of how to do this.

Installazione

The XML Data Access Service is packaged and installed as part of the SDO extension. Please Refer SDO installation instructions.

Limitations

The SDO 2.0 specification defines the mapping between XML types and SDO types. With Java SDO, this mapping is implemented by the XMLHelper. With SDO for PHP, this mapping is implemented by the XML Data Access Services. The XML DAS implements the mapping described in the SDO 2.0 specification with the following restrictions:

XML Simple Types

Simple Type with abstract="true" - no PHP support for SDO abstract types.
Simple Type with sdoJava:instanceClass - no PHP equivalent provided.
Simple Type with sdoJava:extendedInstanceClass - no PHP equivalent provided.
Simple Type with list of itemType.
Simple Type with union.

XML Complex Types

Complex Type with abstract="true" - no PHP support for SDO abstract types.
Complex Type with sdo:aliasName - no PHP support for SDO Type aliases.
Complex Type with open content - no PHP support for SDO open types.
Complex Type with open attribute - no PHP support for SDO open types.

XSD Attribute

Attribute with sdo:aliasName - no PHP support for SDO property aliases.
Attribute with default value - no PHP support for SDO property defaults.
Attribute with fixed value - no PHP support for SDO read-only properties or default values.
Attribute reference.
Attribute with sdo:string - no support for sdo:string="true".
Attribute referencing a DataObject with sdo:propertyType - no support for sdo:propertyType="...".
Attribute with bi-directional property to a DataObject with sdo:oppositeProperty and sdo:propertyType - no PHP support for SDO opposite.

XSD Elements

Element with sdo:aliasName - no PHP support for SDO property aliases.
Element reference.
Element with nillable.
Element with substitution group.

XSD Elements with Simple Type

Element of SimpleType with default - no PHP support for SDO defaults
Element of SimpleType with fixed value - no PHP support for SDO read-only properties or default values.
Element of SimpleType with sdo:string - no support for sdo:string="true".
Element referencing a DataObject with sdo:propertyType - no support for sdo:propertyType="..."
Element with bi-directional reference to a DataObject with sdo:oppositeProperty and sdo:propertyType - no PHP support for SDO opposite.

Esempi

The following examples are based on the letter example described in the SDO documentation. The examples assume the XML Schema for the letter is contained in a file letter.xsd and the letter instance is in the file letter.xml. These two files are reproduced here:

Esempio 1. Loading, altering, and saving an XML document

The following example shows how an XML document can be loaded from a file, altered, and written back.

<?php
try {
    $xmldas = SDO_DAS_XML::create("letter.xsd");
    $xdoc = $xmldas->loadFromFile("letter.xml");
    $do = $xdoc->getRootDataObject();
    $do->date = "September 03, 2004";
    $do->firstName = "Anantoju";
    $do->lastName = "Madhu";
    $xmldas->saveDocumentToFile($xdoc, "letter-out.xml");
} catch (SDO_TypeNotFoundException $e) {
    print("Type is not defined in the xsd file");
} catch (SDO_DAS_XML_ParserException $e) {
    print("Problem while parsing");
}
?>

An instance of the XML DAS is first obtained from the SDO_DAS_XML::create() method, which is a static method of the SDO_DAS_XML class. The location of the xsd is passed as a parameter. Once we have an instance of the XML DAS initialised with a given schema, we can use it to load the instance document using the loadFromFile() method. There is also a loadFromString() method if you want to load an XML instance document from a string. If the instance document loads successfully, you will be returned an object of type SDO_DAS_XML_Document, on which you can call the getRootDataObject() method to get the SDO data object which is the root of the SDO data graph. You can then use SDO operations to change the graph. In this example we alter the date, firstName, and lastName properties. Then we use the saveDocumentToFile() method to write the changed document back to the file system.

This will write the following to letter-out.xml.

<?xml version="1.0" encoding="UTF-8"?>
<FormLetter xmlns="http://letterSchema" xsi:type="FormLetter" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <date>September 03, 2004</date>
  Mutual of Omaha
  Wild Kingdom, USA
  Dear
  <firstName>Anantoju</firstName>
  <lastName>Madhu</lastName>
  Please buy more shark repellent.
  Your premium is past due.
</FormLetter>

Esempio 2. Creating a new XML document

The previous example loaded the document from a file. This example shows how to create an SDO data graph in memory. In this example it is then saved to an XML string. Furthermore, because the letter contains both structured and unstructured content, it uses the Sequence API as well assignments to properties to construct the data graph.

<?php 
try {
    $xmldas = SDO_DAS_XML::create("letter.xsd");
    try {
        $do = $xmldas->createDataObject("http://letterSchema", "FormLetter");
        $seq = $do->getSequence();
        $seq->insert("April 09, 2005", NULL, 'date');
        $seq->insert("Acme Inc. ", NULL, NULL);
        $seq->insert("United Kingdom. ");
        $seq->insert("Dear", NULL, NULL);
        $seq->insert("Tarun", NULL, "firstName");
        $seq->insert("Nayaraaa", NULL, "lastName");
        $do->lastName = "Nayar";
        $seq->insert("Please note that your order number ");
        $seq->insert(12345);
        $seq->insert(" has been dispatched today. Thanks for your business with us.");
        $type = $do->getType();
        print($xmldas->saveDataObjectToString($do, $type[0], $type[1]));
    } catch (SDO_Exception $e) {
        print($e);
    }
} catch (SDO_TypeNotFoundException $e) {
    print("Type is not defined in the xsd file");
} catch (SDO_DAS_XML_ParserException $e) {
    print("Problem while parsing");
}
?>

This will emit the following output (line breaks have been inserted for readability):

<?xml version="1.0" encoding="UTF-8"?>
<FormLetter xmlns="http://letterSchema" xsi:type="FormLetter" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<date>April 09, 2005</date>
Acme Inc. United Kingdom. 
Dear
<firstName>Tarun</firstName>
<lastName>Nayar</lastName>
Please note that your order number 12345 has been 
dispatched today. Thanks for your business with us.
</FormLetter>

Esempio 3. Setting XML document properties

This third example shows you how to use the SDO_DAS_XML_Document class. SDO_DAS_XML_Document class is provided to get and set properties of the XML declaration such as version, schema location, encoding and so on.

<?php
try {
    $xmldas = SDO_DAS_XML::create("letter.xsd");
    $xdoc = $xmldas->loadFromFile("letter.xml");
    print("Encoding is set to : " . $xdoc->getEncoding() . "\n");
    print("XML Version : " . $xdoc->getXMLVersion() . "\n");
    $xdoc->setXMLVersion("1.1");
    print($xmldas->saveDocumentToString($xdoc));
} catch (SDO_TypeNotFoundException $e) {
    print("Type is not defined in the xsd file");
} catch (SDO_DAS_XML_ParserException $e) {
    print("Problem while parsing");
}
?>

The first three lines of output show how the encoding and XML version has been obtained from the document, and how the XML version has been set in the XML header.

Encoding is set to : UTF-8
XML Version : 1.0
<?xml version="1.1" encoding="UTF-8"?>
...

Classi predefinite

The XML DAS provides three classes. The SDO_DAS_XML which is the main class used to fetch the data from the XML source and also can used to write the data back. The next one is SDO_DAS_XML_Document class, which is basically useful to get/set the XML declarations such as encoding, version etc. And the last class is SDO_DAS_XML_ParserException which will be thrown for any parser exceptions while loading xsd/xml file.

SDO_DAS_XML

This is the main class of XML DAS, which is used fetch the data from the xml source and also used to write the data back. Other than the methods to load and save xml files, it also has a method called createDataObject which can be used to create an empty DataObject of a given type.

Metodi

create This is the only static method available in SDO_DAS_XML class. Used to construct SDO_DAS_XML object.
createDataObject Can be used to construct the DataObject of a given type.
loadFromFile Loads the xml instance document from a file. This file can be at local file system or it can be on a remote host.
loadFromString same as the above method. Loads the xml instance which is available as string.
saveDataObjectToFile save SDO_DataObject to a file.
saveDataObjectToString save SDO_DataObject to a xml file.
saveDocumentToFile save SDO_DAS_XML_Document object as a xml file.
saveDocumentToString save SDO_DAS_XML_Document object as a xml string.

SDO_DAS_XML_Document

This class can be used to get/set XML Declarations such as encoding, schema location etc.

Metodi

getEncoding gets the encoding string.
getNoNamespaceSchemaLocation gets the no namespace schema location.
getRootDataObject gets the root DataObject.
getRootElementName gets the root DataObject's name.
getRootElementURI gets the root DataObject's URI.
getSchemaLocation gets schema location.
getXMLDeclaration gets whether xml declaration is set ot not.
getXMLVersion gets the xml version.
setEncoding sets the encoding string with the given value.
setNoNamespaceSchemaLocation sets the no namespace schema location with the given value.
setSchemaLocation sets the schema location with the given value.
setXMLDeclaraion to set/unset the xml declaration.
setXMLVersion sets the xml version with the given value.

SDO_DAS_XML_ParserException

Is a subclass of SDO_Exception . Thrown for any parser errors while loading the xsd/xml file.

Sommario
SDO_DAS_XML_Document::getEncoding -- Returns encoding string.
SDO_DAS_XML_Document::getNoNamespaceSchemaLocation -- Returns no namespace schema location.
SDO_DAS_XML_Document::getRootDataObject -- Returns the root SDO_DataObject.
SDO_DAS_XML_Document::getRootElementName -- Returns root element's name.
SDO_DAS_XML_Document::getRootElementURI -- Returns root element's URI string.
SDO_DAS_XML_Document::getSchemaLocation -- Returns schema location.
SDO_DAS_XML_Document::getXMLDeclaration -- Returns whether the xml declaration is set or not.
SDO_DAS_XML_Document::getXMLVersion -- Returns xml declaration string.
SDO_DAS_XML_Document::setEncoding -- Sets the given string as encoding.
SDO_DAS_XML_Document::setNoNamespaceSchemaLocation -- Sets the given string as no namespace schema location.
SDO_DAS_XML_Document::setSchemaLocation -- Sets the given string as schema location.
SDO_DAS_XML_Document::setXMLDeclaration -- Sets the xml declaration.
SDO_DAS_XML_Document::setXMLVersion -- Sets the given string as xml version.
SDO_DAS_XML::create -- To create SDO_DAS_XML object for a given schema file.
SDO_DAS_XML::createDataObject -- Creates SDO_DataObject for a given namespace URI and type name.
SDO_DAS_XML::loadFromFile -- Returns SDO_DAS_XML_Document object for a given path to xml instance document.
SDO_DAS_XML::loadFromString -- Returns SDO_DAS_XML_Document for a given xml instance string.
SDO_DAS_XML::saveDataObjectToFile -- Saves the SDO_DataObject object to File.
SDO_DAS_XML::saveDataObjectToString -- Saves the SDO_DataObject object to string.
SDO_DAS_XML::saveDocumentToFile -- Saves the SDO_DAS_XML_Document object to a file.
SDO_DAS_XML::saveDocumentToString -- Saves the SDO_DAS_XML_Document object to a string.

xsd_file: Path to XSD Schema file.

Valori restituiti

Returns SDO_DAS_XML object on success otherwise throws an exception as described below.

Eccezioni

SDO_TypeNotFoundException: Thrown if a type is not defined in the underlying model.
SDO_DAS_XML_ParserException: Thrown for any symantical problems while parsing the given XSD File.

SDO_DAS_XML::createDataObject

(no version information, might be only in CVS)

SDO_DAS_XML::createDataObject -- Creates SDO_DataObject for a given namespace URI and type name.

Descrizione

SDO_DataObject SDO_DAS_XML::createDataObject ( string namespace_uri, string type_name )

Avvertimento

Creates SDO_DataObject for a given namespace URI and type name. The type should be defined in the underlying model otherwise SDO_TypeNotFoundException will be thrown.

Elenco dei parametri

namespace_uri: Namespace URI of the type name.
type_name: Type Name.

Valori restituiti

Returns SDO_DataObject on success.

Eccezioni

SDO_TypeNotFoundException: Thrown if a type is not defined in the underlying model.

SDO_DAS_XML::loadFromFile

(no version information, might be only in CVS)

SDO_DAS_XML::loadFromFile -- Returns SDO_DAS_XML_Document object for a given path to xml instance document.

Descrizione

SDO_XMLDocument SDO_DAS_XML::loadFromFile ( string xml_file )

Avvertimento

Constructs the tree of SDO_DataObjects from the given address to xml instance document. Returns SDO_DAS_XML_Document Object. Use SDO_DAS_XML_Document::getRootDataObject method to get root data object.

Elenco dei parametri

xml_file: Path to Instance document. This can be a path to a local file or it can be a URL.

Valori restituiti

Returns SDO_DAS_XML_Document object on Success or throws exception as described.

Eccezioni

SDO_TypeNotFoundException: Thrown if a type is not defined by the underlying model.
SDO_PropertyNotFoundException: Thrown if the a property within a type is not defined in the underlying model.
SDO_DAS_XML_ParserException: Thrown for any symantical problems while parsing the given XSD File.

SDO_DAS_XML::loadFromString

(no version information, might be only in CVS)

SDO_DAS_XML::loadFromString -- Returns SDO_DAS_XML_Document for a given xml instance string.

Descrizione

SDO_DAS_XML_Document SDO_DAS_XML::loadFromString ( string xml_string )

Avvertimento

Constructs the tree of SDO_DataObjects from the given xml instance string. Returns SDO_DAS_XML_Document Object. Use SDO_DAS_XML_Document::getRootDataObject method to get root data object.

Elenco dei parametri

xml_string: xml string.

Valori restituiti

Returns SDO_DAS_XML_Document object on Success or throws exception as described.

Eccezioni

SDO_TypeNotFoundException: Thrown if a type is not defined by the underlying model.
SDO_PropertyNotFoundException: Thrown if the a property within a type is not defined in the underlying model.
SDO_DAS_XML_ParserException: Thrown for any problems while parsing the given XSD File.

SDO_DAS_XML::saveDataObjectToFile

(no version information, might be only in CVS)

SDO_DAS_XML::saveDataObjectToFile -- Saves the SDO_DataObject object to File.

Descrizione

void SDO_DAS_XML::saveDataObjectToFile ( SDO_DataObject do, string root_uri, string root_name, string xml_file )

Avvertimento

Saves the SDO_DataObject object as an XML File.

Elenco dei parametri

do: DataObject, which needs to be saves as an XML File.
root_uri: URI string for the root DataObject.
root_name: Type name of the root DataObject.

Valori restituiti

None.

SDO_DAS_XML::saveDataObjectToString

(no version information, might be only in CVS)

SDO_DAS_XML::saveDataObjectToString -- Saves the SDO_DataObject object to string.

Descrizione

string SDO_DAS_XML::saveDataObjectToString ( SDO_DataObject do, string root_uri, string root_name )

Avvertimento

Saves the SDO_DataObject object as an XML string.

Elenco dei parametri

do: DataObject, which needs to be saves as an XML File.
root_uri: URI string for the root DataObject.
root_name: Type name of the root DataObject.

Valori restituiti

xml string

SDO_DAS_XML::saveDocumentToFile

(no version information, might be only in CVS)

SDO_DAS_XML::saveDocumentToFile -- Saves the SDO_DAS_XML_Document object to a file.

Descrizione

void SDO_DAS_XML::saveDocumentToFile ( SDO_XMLDocument xdoc, string xml_file )

Avvertimento

Saves the SDO_DAS_XML_Document object to a file.

Elenco dei parametri

xdoc: SDO_DAS_XML_Document object.
xml_file: xml file.

Valori restituiti

SDO_DAS_XML::saveDocumentToString

(no version information, might be only in CVS)

SDO_DAS_XML::saveDocumentToString -- Saves the SDO_DAS_XML_Document object to a string.

Descrizione

string SDO_DAS_XML::saveDocumentToString ( SDO_XMLDocument xdoc )

Avvertimento

Saves the SDO_DAS_XML_Document object to string.

Elenco dei parametri

xdoc: SDO_DAS_XML_Document object.

Valori restituiti

xml string.

CXXX. SDO Relational Data Access Service Functions

Introduzione

Avvertimento

In order to use the Relational Data Access Service for Service Data Objects, you will need to understand some of the concepts behind SDO: the data graph, the data object, the disconnected way of working, the change summary, XPath and property expressions, and so on. If you are not familiar with these ideas, you might want to look first at the section on SDO. In addition, the Relational DAS makes use of the PDO extension to isolate itself from specifics of different back-end relational databases. In order to use the Relational DAS you will need to be able to create and pass a PDO database connection; for this reason you might also want to take a look at the section on PDO.

The job of the Relational DAS is to move data between the application and a relational database. In order to do this it needs to be told the mapping between the database entities - tables, columns, primary keys and foreign keys - and the elements of the SDO model - types, properties, containment properties and so on. You specify this information as metadata when you construct the Relational DAS.

Overview of Operation

The first step is to call the Relational DAS's constructor, passing the metadata that defines the mapping between database and SDO model. There are examples of this below.
The next step might be to call the executeQuery() or executePreparedQuery() methods on the Relational DAS, passing either a literal SQL statement for the DAS to prepare and execute, or a prepared statement with placeholders and a list of values to be inserted. You may also need to specify a small amount of metadata about the query itself, so that the Relational DAS knows exactly what columns will be returned from the database and in what order. You will also need to pass a PDO database connection.
The return value from executeQuery() or executePreparedQuery() is a normalised data graph containing all the data from the result set. For a query that returns data obtained from a number of tables, this graph will contain a number of data objects, linked by SDO containment references. There may also be SDO non-containment references within the data.
Once the query has been executed and the data graph constructed, there is no need for either that instance of the the Relational DAS or the database connection. There are no locks held on the database. Both the Relational DAS and the PDO database connection can be garbage collected.
Quite possibly the data in the data graph will go through a number of modifications. The data graph can be serialised into the PHP session and so may have a lifetime beyond just one client-server interaction. Data objects can be created and added to the graph, the data objects already in the graph can be deleted, and data objects in the graph can be modified.
Finally, the changes made to the data graph can be applied back to the database using the applyChanges() method of the Relational DAS. For this, another instance of the Relational DAS must be constructed, using the same metadata, and another connection to the database obtained. The connection and the data graph are passed to applyChanges(). At this point the Relational DAS examines the change summary and generates the necessary INSERT, UPDATE and DELETE SQL statements to apply the changes. Any UPDATE and DELETE statements are qualified with the original values of the data so that should the data have changed in the database in the meantime this will be detected. Assuming no such collisions have occurred the changes will be committed to the database. The application can then continue to work with the data graph, make more changes and apply them, or can discard it.

There are other ways of working with the data in the database: it is possible to just create data objects and write them to the database without a preliminary call to executeQuery(), for example. This scenario and others are explored in the Examples section below.

Installazione

The installation instructions for all the SDO components are in the SDO install section of the SDO documentation.

In any case, the essential facts are that the Relational DAS is written in PHP and it should be placed somewhere on the PHP include_path .

Your application will of course need to include the Relational DAS with a statement like this:
<?php require_once 'SDO/DAS/Relational.php'; ?>

Requisiti

The Relational DAS requires that the SDO extension be installed. The SDO extension requires a version of PHP 5.1, and the Relational DAS requires a recent version that contains an important fix for PDO. The most up-to-date information about required levels of PHP should be found in the changelog for the package on PECL. At the time of writing, though, the Relational DAS requires the most recent beta level of PHP 5.1, that is PHP 5.1.0b3.

The Relational DAS uses PDO to access the relational database, and so should run with a variety of different relational databases. At the time of writing it has been tested in the following configurations

MySQL 4.1.17, on Windows. The Relational DAS operates correctly with the php_pdo_mysql driver that comes with the pre-built binaries for PHP 5.1.0b3.
MySQL 4.1.17, on Linux. It is necessary to have the most up-to-date PDO driver for MySQL, which comes built in to PHP 5.1.0b3. It may be necessary to uninstall the usual driver that would have come from PECL using pear uninstall pdo_mysql . You will need to configure PHP with the --with-pdo-mysql option.
DB2 8.2 Personal Edition, on Windows. The Relational DAS operates correctly with the php_pdo_odbc driver that comes with the pre-built binaries for PHP 5.1.0b3.
DB2 8.2 Personal Developer's Edition, on Linux. The Developer's Edition is needed because it contains the include files needed when PHP is configured and built. You will need to configure PHP with the --with-pdo-odbc=ibm-db2 option.

The Relational DAS applies changes to the database within a user-delimited transaction: that is, it issues a call to PDO::beginTransaction() before beginning to apply changes, and PDO::commit() or PDO::rollback() on completion. Whichever database is chosen, the database and the PDO driver for the database must support these calls.

Limitations

There are the following limitations in the current release of the Relational DAS:

No support for nulls. There is no support for SQL NULL type. It is not legal to assign PHP NULL to a data object property and the Relational DAS will not write that back as a NULL to the database. If nulls are found in the database on a query, the property will remain unset.
Only two types of SDO relationship. The metadata described below allows the Relational DAS to model just two types of SDO relationship: multi-valued containment properties and single-valued non-containment properties. In SDO, whether a property is single- or multi-valued, and whether it is containment or non-containment, are independent. The full range of possibilities that SDO allows cannot all be defined. There may be relationships that it would be useful to model but which the current implementation cannot manage. One example is a single-valued containment relationship.
No support for the full range of SDO data types. The Relational DAS defines all primitive properties in the SDO model as being of type string. SDO defines a richer set of types containing various integer, float, boolean and data and time types. String is adequate for the purposes of the Relational DAS since the combination of PHP, PDO and the database will ensure that values passed as strings will be converted to the proper type before being put in the database. This does affect some scenarios in which the Relational DAS has to work with a data graph that has come from or will go to a different DAS.
Only one foreign key per table. The metadata only provides the means to specify one foreign key per table. This foreign key may be mapped to one of the two types of SDO relationship supported. Obviously there are some scenarios that cannot be described under this limitation - it is not possible to have two non-containment references from one table to another for example.

Esempi

This section illustrates how the Relational DAS can be used to create, retrieve, update and delete data in a relational database. Many of the examples are illustrated with a three-table database that contains companies, departments within those companies, and employees that work in those departments. This example is used in a number of places within the SDO literature. See the examples section of the Service Data Objects specification or the Examples section of the documentation for the SDO extension.

The Relational DAS is constructed with metadata that defines the relational database and how it should be mapped to SDO. The long section that follows describes this metadata and how to construct the Relational DAS. The examples that follow it all assume that this metadata is in an included php file.

The examples below and others can all be found in the Scenarios directory in the Relational DAS package.

The Relational DAS throws exceptions in the event that it finds errors in the metadata or errors when executing SQL statements against the database. For brevity the examples below all omit the use of try/catch blocks around the calls to the Relational DAS.

These examples all differ from the expected use of SDO in two important respects.

First, they show all interactions with the database completed within one script. In this respect these scenarios are not realistic but are chosen to illustrate just the use of the Relational DAS. It is expected that interactions with the database will be separated in time and the data graph serialised and deserialised into the PHP session one or more times as the application interacts with an end user.

Second, all queries executed against the database use hard-coded queries with no variables substituted. In this case it is safe to use the simple executeQuery() call, and this is what the examples illustrate. In practice, though, it is unlikely that the SQL statement is known entirely ahead of time. In order to allow variables to be safely substituted into the SQL queries, without running the risk of injecting SQL with unknown effects, it is safer to use the executePreparedQuery() which takes a prepared SQL statement containing placeholders and a list of values to be substituted.

Specifying the metadata

This first long section describes in detail how the metadata describing the database and the required SDO model is supplied to the Relational DAS.

When the constructor for the Relational DAS is invoked, it needs to be passed several pieces of information. The bulk of the information, passed as an associative array in the first argument to the constructor, tells the Relational DAS what it needs to know about the relational database. It describes the names of the tables, columns, primary keys and foreign keys. It should be fairly easy to understand what is required, and once written it can be placed in a php file and included when needed. The remainder of the information, passed in the second and third arguments to the constructor, tells the Relational DAS what it needs to know about the relationships between objects and the shape of the data graph; it ultimately determines how the data from the database is to be normalised into a graph.

Database metadata

The first argument to the constructor describes the target relational database.

Each table is described by an associative array with up to four keys.

Key	Value
name	The name of the table.
columns	An array listing the names of the columns, in any order.
PK	The name of the column containing the primary key.
FK	An array with two entries, 'from' and 'to', which define a column containing a foreign key, and a table to which the foreign key points. If there are no foreign keys in the table then the 'FK' entry does not need to be specified. Only one foreign key can be specified. Only a foreign key pointing to the primary key of a table can be specified.

<?php
/*****************************************************************
* METADATA DEFINING THE DATABASE
******************************************************************/
$company_table = array (
    'name' => 'company',
    'columns' => array('id', 'name',  'employee_of_the_month'),
    'PK' => 'id',
    'FK' => array (
        'from' => 'employee_of_the_month',
        'to' => 'employee',
        ),
    );
$department_table = array (
    'name' => 'department', 
    'columns' => array('id', 'name', 'location', 'number', 'co_id'),
    'PK' => 'id',
    'FK' => array (
        'from' => 'co_id',
        'to' => 'company',
        )
    );
$employee_table = array (
    'name' => 'employee',
    'columns' => array('id', 'name', 'SN', 'manager', 'dept_id'),
    'PK' => 'id',
    'FK' => array (
        'from' => 'dept_id',
        'to' => 'department',
        )
    );
$database_metadata = array($company_table, $department_table, $employee_table);
?>

This metadata corresponds to a relational database that might have been defined to MySQL as:

create table company (
   id integer auto_increment,
   name char(20),
   employee_of_the_month integer,
   primary key(id)
 );
 create table department (
   id integer auto_increment,
   name char(20),
   location char(10),
   number integer(3),
   co_id integer,
   primary key(id)
 );
 create table employee (
   id integer auto_increment,
   name char(20),
   SN char(4),
   manager tinyint(1),
   dept_id integer,
   primary key(id)
 );

or to DB2 as:

create table company ( \
    id integer not null generated by default as identity,  \
    name varchar(20), \
    employee_of_the_month integer, \
    primary key(id) )
create table department ( \
    id integer not null generated by default as identity, \
    name varchar(20), \
    location varchar(10), \
    number integer, \
    co_id integer, \
    primary key(id) )
create table employee ( \
    id integer not null generated by default as identity, \
    name varchar(20), \
    SN char(4), \
    manager smallint, \
    dept_id integer, \
    primary key(id) )

Note that although in this example there are no foreign keys specified to the database and so the database is not expected to enforce referential integrity, the intention behind the co_id column on the department table and the dept_id column on the employee table is they should contain the primary key of their containing company or department record, respectively. So these two columns are acting as foreign keys.

There is a third foreign key in this example, that from the employee_of_the_month column of the company record to a single row of the employee table. Note the difference in intent between this foreign key and the other two. The employee_of_the_month column represents a single-valued relationship: there can be only one employee of the month for a given company. The co_id and dept_id columns represent multi-valued relationships: a company can contain many departments and a department can contain many employees. This distinction will become evident when the remainder of the metadata picks out the company-department and department-employee relationships as containment relationships.

There are a few simple rules to be followed when constructing the database metadata:

All tables must have primary keys, and the primary keys must be specified in the metadata. Without primary keys it is not possible to keep track of object identities. As you can see from the SQL statements that create the tables, primary keys can be auto-generated, that is, generated and assigned by the database when a record is inserted. In this case the auto-generated primary key is obtained from the database and inserted into the data object immediately after the row is inserted into the database.
It is not necessary to specify in the metadata all the columns that exist in the database, only those that will be used. For example, if the company table had another column that the application did not want to access with SDO, this need not be specified in the metadata. On the other hand it would have done no harm to specify it: if specified in the metadata but never retrieved, or assigned to by the application, then the unused column will not affect anything.
In the database metadata note that the foreign key definitions identify not the destination column in the table which is pointed to, but the table name itself. Strictly, the relational model permits the destination of a foreign key to be a non-primary key. Only foreign keys that point to a primary key are useful for constructing the SDO model, so the metadata specifies the table name. It is understood that the foreign key points to the primary key of the given table.

Given these rules, and given the SQL statements that define the database, the database metadata should be easy to construct.

What the Relational DAS does with the metadata

The Relational DAS uses the database metadata to form most of the SDO model. For each table in the database metadata, an SDO type is defined. Each column which can represent a primitive value (columns which are not defined as foreign keys) are added as properties to the SDO type.

All primitive properties are given a type of string in the SDO model, regardless of their SQL type. When writing values back to the database the Relational DAS will create SQL statements that treat the values as strings, and the database will convert them to the appropriate type.

Foreign keys are interpreted in one of two ways, depending on the metadata in the third argument to the constructor that defines the SDO containment relationships. A discussion of this is therefore deferred until the section on SDO containment references below.

Specifying the application root type

The second argument to the constructor is the application root type. The true root of each data graph is an object of a special root type and all application data objects come somewhere below that. Of the various application types in the SDO model, one has to be the application type immediately below the root of the data graph. If there is only one table in the database metadata, the application root type can be inferred, and this argument can be omitted.

Specifying the SDO containment references

The third argument to the constructor defines how the types in the model are to be linked together to form a graph. It identifies the parent-child relationships between the types which collectively form a graph. The relationships need to be supported by foreign keys to be found in the data, in a way shortly to be described.

The metadata is an array containing one or more associative arrays, each of which identifies a parent and a child. The example below shows a parent-child relationship from company to department, and another from department to employee. Each of these will become an SDO multi-valued containment property in the SDO model.

<?php
$department_reference = array( 'parent' => 'company', 'child' => 'department');
$employee_reference = array( 'parent' => 'department', 'child' => 'employee');

$SDO_reference_metadata = array($department_reference, $employee_reference);           
?>

Foreign keys in the database metadata are interpreted as either multi-valued containment properties or single-valued non-containment properties, depending on whether they have a corresponding SDO containment reference specified in the metadata. In the example here, the foreign keys from department to company (the co_id column in the department table) and from employee to department (the dept_id column in the employee table) are interpreted as supporting the SDO containment references. Each containment reference mentioned in the SDO containment references metadata must have a corresponding foreign key present in the database and defined in the database metadata. The values of the foreign key columns for containment references do not appear in the data objects, instead they are represented by the containment reference from the parent to the child. So the co_id column in the department row in the database, for example, does not appear as a property on the department type, but instead as a containment relationship called department on the company type. Note that the foreign key and the parent-child relationship appear to have opposite senses: the foreign key points from the department to the company, but the parent-child relationship points from company to department.

The third foreign key in this example, the employee_of_the_month , is handled differently. This is not mentioned in the SDO containment references metadata. As a consequence this is interpreted in the second way: it becomes a single-valued non-containment reference on the company object, to which can be assigned references to SDO data objects of the employee type. It does appear as a property on the company type. The way to assign a value to it in the SDO data graph is to have a graph that contains an employee object through the containment references, and to assign the object to it. This is illustrated in the later examples below.

One-table examples

The following set of examples all use the Relational DAS to work with a data graph containing just one application data object, a single company and the data just to be found the company table. These examples do not exercise the power of SDO or the Relational DAS and of course the same result could be achieved more economically with direct SQL statements but they are intended to illustrate how to work with the Relational DAS.

For this very simple scenario it would be possible to simplify the database metadata to include just the company table - if that were done the second and third arguments to the constructor and the column specifier used in the query example would become optional.

Esempio 1. Creating a data object
The simplest example is that of creating a single data object and writing it to the database. In this example a single company object is created, its name is set to 'Acme', and the Relational DAS is called to write the changes to the database. The company name is set here using the property name method. See the Examples section on the SDO extension for other ways of accessing the properties of an object.
Data objects can only be created when you have a data object to start with, however. It is for that reason that the first call to the Relational DAS here is to obtain a root object. This is in effect how to ask for an empty data graph - the special root object is the true root of the tree. The company data object is then created with a call to createDataObject() on the root object. This creates the company data object and inserts it in the graph by inserting into a multi-valued containment property on the root object called 'company'.
When the Relational DAS is called to apply the changes a simple insert statement 'INSERT INTO company (name} VALUES ("Acme");' will be constructed and executed. The auto-generated primary key will be set into the data object and the change summary will be reset, so that it would be possible to continue working with the same data object, modify it, and apply the newer changes a second time.
<?php require_once 'SDO/DAS/Relational.php'; require_once 'company_metadata.inc.php'; /************************************************************** * Construct the DAS with the metadata ***************************************************************/ $das = new SDO_DAS_Relational ($database_metadata,'company',$SDO_reference_metadata); /************************************************************** * Obtain a root object and create a company object underneath. * Make a simple change to the data object. ***************************************************************/ $root = $das -> createRootDataObject(); $acme = $root -> createDataObject('company'); $acme->name = "Acme"; /************************************************************** * Get a database connection and write the object to the database ***************************************************************/ $dbh = new PDO(PDO_DSN,DATABASE_USER,DATABASE_PASSWORD); $das -> applyChanges($dbh, $root); ?>

Esempio 2. Retrieving a data object
In this example a single data object is retrieved from the database - or possibly more than one if there is more than one company called 'Acme'. For each company returned, the name and id properties are echoed.
In this example the third argument to executeQuery(), the column specifier is needed as there are other tables in the metadata with column names of name and id. If there were no possible ambiguity it could be omitted.
<?php require_once 'SDO/DAS/Relational.php'; require_once 'company_metadata.inc.php'; /************************************************************** * Construct the DAS with the metadata ***************************************************************/ $das = new SDO_DAS_Relational ($database_metadata,'company',$SDO_reference_metadata); /************************************************************** * Get a database connection ***************************************************************/ $dbh = new PDO(PDO_DSN,DATABASE_USER,DATABASE_PASSWORD); /************************************************************** * Issue a query to obtain a company object - possibly more if they exist ***************************************************************/ $root = $das->executeQuery($dbh, 'select name, id from company where name="Acme"', array('company.name', 'company.id') ); /************************************************************** * Echo name and id ***************************************************************/ foreach ($root['company'] as $company) { echo "Company obtained from the database has name = " . $company['name'] . " and id " . $company['id'] . "\n"; } ?>

Esempio 3. Updating a data object
This example combines the previous two, in the sense that in order to be updated the object must first be retrieved. The application code reverses the company name (so 'Acme' becomes 'emcA') and then the changes are written back to the database in the same way that they were when the object was created. Because the query searches for the name both ways round the program can be run repeatedly to find the company and reverse its name each time.
In this example the same instance of the Relational DAS is reused for the applyChanges(), as is the PDO database handle. This is quite alright; it also alright to allow the previous instances to be garbage collected and to obtain new instances. No state data regarding the graph is held the Relational DAS once it has returned a data graph to the application. All necessary data is either within the graph itself, or can be reconstructed from the metadata.
<?php require_once 'SDO/DAS/Relational.php'; require_once 'company_metadata.inc.php'; /************************************************************** * Construct the DAS with the metadata ***************************************************************/ $das = new SDO_DAS_Relational ($database_metadata,'company',$SDO_reference_metadata); /************************************************************** * Get a database connection ***************************************************************/ $dbh = new PDO(PDO_DSN,DATABASE_USER,DATABASE_PASSWORD); /************************************************************** * Issue a query to obtain a company object - possibly more if they exist ***************************************************************/ $root = $das->executeQuery($dbh, 'select name, id from company where name="Acme" or name="emcA"', array('company.name', 'company.id') ); /************************************************************** * Alter the name of just the first company ***************************************************************/ $company = $root['company'][0]; echo "obtained a company with name of " . $company->name . "\n"; $company->name = strrev($company->name); /************************************************************** * Write the change back ***************************************************************/ $das->applyChanges($dbh,$root); ?>

Esempio 4. Deleting a data object
Any companies called 'Acme' or its reverse 'emcA' are retrieved. They are then all deleted from the graph with unset.
In this example they are all deleted in one go by unsetting the containing reference. It is also possible to delete them individually.
<?php require_once 'SDO/DAS/Relational.php'; require_once 'company_metadata.inc.php'; /************************************************************** * Construct the DAS with the metadata ***************************************************************/ $das = new SDO_DAS_Relational ($database_metadata,'company',$SDO_reference_metadata); /************************************************************** * Get a database connection ***************************************************************/ $dbh = new PDO(PDO_DSN,DATABASE_USER,DATABASE_PASSWORD); /************************************************************** * Issue a query to obtain a company object - possibly more if they exist ***************************************************************/ $root = $das->executeQuery($dbh, 'select name, id from company where name="Acme" or name="emcA"', array('company.name', 'company.id') ); /************************************************************** * Delete any companies found from the data graph ***************************************************************/ unset($root['company']); /************************************************************** * Write the change(s) back ***************************************************************/ $das->applyChanges($dbh,$root); ?>

Two-table examples

The following set of examples all use two tables from the company database: the company and department tables. These examples exercise more of the function of the Relational DAS.

In this series of examples a company and department are created, retrieved, updated, and finally deleted. This illustrates the lifecycle for a data graph containing more than one object. Note that this example clears out the company and department tables at the start so that the exact results of the queries can be known.

You can find these examples combined into one script called 1cd-CRUD in the Scenarios directory in the Relational DAS package.

Esempio 5. One company, one department - Create
As in the earlier example of creating just one company data object, the first action after constructing the Relational DAS is to call createRootDataObject() to obtain the special root object of the otherwise empty data graph. The company object is then created as a child of the root object, and the department object as a child of the company object.
When it comes to applying the changes, the Relational DAS has to perform special processing to maintain the foreign keys that support the containment relationships, especially if auto-generated primary keys are involved. In this example, the relationship between the auto-generated primary key id in the company table and the co_id column in the department table must be maintained. When inserting a company and department for the first time the Relational DAS has to first insert the company row, then call PDO's getLastInsertId() method to obtain the auto-generated primary key, then add that as the value of the co_id column when inserting the department row.
<?php require_once 'SDO/DAS/Relational.php'; require_once 'company_metadata.inc.php'; /************************************************************************************* * Empty out the two tables *************************************************************************************/ $dbh = new PDO(PDO_DSN,DATABASE_USER,DATABASE_PASSWORD); $pdo_stmt = $dbh->prepare('DELETE FROM COMPANY;'); $rows_affected = $pdo_stmt->execute(); $pdo_stmt = $dbh->prepare('DELETE FROM DEPARTMENT;'); $rows_affected = $pdo_stmt->execute(); /************************************************************** * Create a company with name Acme and one department, the Shoe department ***************************************************************/ $dbh = new PDO(PDO_DSN,DATABASE_USER,DATABASE_PASSWORD); $das = new SDO_DAS_Relational ($database_metadata,'company',$SDO_reference_metadata); $root = $das -> createRootDataObject(); $acme = $root -> createDataObject('company'); $acme -> name = "Acme"; $shoe = $acme->createDataObject('department'); $shoe->name = 'Shoe'; $das -> applyChanges($dbh, $root); ?>

Esempio 6. One company, one department - Retrieve and Update
In this case the SQL query passed to executeQuery() performs an inner join to join the data from the company and department tables. Primary keys for both the company and department tables must be included in the query. The result set is re-normalised to form a normalised data graph. Note that a column specifier is passed as the third argument to the executeQuery() call enabling the Relational DAS to know which column is which in the result set.
Note that the co_id column although used in the query is not needed in the result set. In order to understand what the Relational DAS is doing when it builds the data graph it may be helpful to visualise what the result set looks like. Although the data in the database is normalised, so that multiple department rows can point through their foreign key to one company row, the data in the result set is non-normalised: that is, if there is one company and multiple departments, the values for the company are repeated in each row. The Relational DAS has to reverse this process and turn the result set back into a normalised data graph, with just one company object.
In this example the Relational DAS will examine the result set and column specifier, find data for both the company and department tables, find primary keys for both, and interpret each row as containing data for a department and its parent company. If it has not seen data for that company before (it uses the primary key to check) it creates a company object and then a department object underneath it. If it has seen data for that company before and has already created the company object it just creates the department object underneath.
In this way the Relational DAS can retrieve and renormalise data for multiple companies and multiple departments underneath them.
<?php require_once 'SDO/DAS/Relational.php'; require_once 'company_metadata.inc.php'; /************************************************************** * Retrieve the company and Shoe department, then delete Shoe and add IT ***************************************************************/ $dbh = new PDO(PDO_DSN,DATABASE_USER,DATABASE_PASSWORD); $das = new SDO_DAS_Relational ($database_metadata,'company',$SDO_reference_metadata); $root = $das->executeQuery($dbh, 'select c.id, c.name, d.id, d.name from company c, department d where d.co_id = c.id', array('company.id','company.name','department.id','department.name')); $acme = $root['company'][0]; // get the first company - will be 'Acme' $shoe = $acme['department'][0]; // get the first department underneath - will be 'Shoe' unset($acme['department'][0]); $it = $acme->createDataObject('department'); $it->name = 'IT'; $das -> applyChanges($dbh, $root); ?>

Esempio 7. One company, two departments - Retrieve and Delete
In this example the company and department are retrieved and then deleted. It is not necessary to delete them individually (although that would be possible) - deleting the company object from the data graph also deletes any departments underneath it.
Note the way that the company object is actually deleted using the PHP unset call. The unset has to be performed on the containing reference which in this case is the company reference on the special root object. You must use:
<?php unset($root['company'][0]); ?>
and not:
<?php unset($acme); //WRONG ?>
Simply unsetting $acme would destroy the variable but leave the data in the data graph untouched.
<?php require_once 'SDO/DAS/Relational.php'; require_once 'company_metadata.inc.php'; /************************************************************** * Retrieve the company and IT department, then delete the whole company ***************************************************************/ $dbh = new PDO(PDO_DSN,DATABASE_USER,DATABASE_PASSWORD); $das = new SDO_DAS_Relational ($database_metadata,'company',$SDO_reference_metadata); $root = $das->executeQuery($dbh, 'select c.id, c.name, d.id, d.name from company c, department d where d.co_id = c.id', array('company.id','company.name','department.id','department.name')); $acme = $root['company'][0]; $it = $acme['department'][0]; unset($root['company'][0]); $das -> applyChanges($dbh, $root); ?>

Three-table example

The following examples use all three tables from the company database: the company, department, and employee tables. These introduce the final piece of function not exercised by the examples above: the non-containment reference employee_of_the_month.

Like the examples above for company and department, this set of examples is intended to illustrate the full lifecycle of such a data graph.

Esempio 8. One company, one department, one employee - Create
In this example a company is created containing one department and just one employee. Note that this example clears out all three tables at the start so that the exact results of the queries can be known.
Note how once the company, department and employee have been created, the employee_of_the_month property of the company can be made to point at the new employee. As this is a non-containment reference, this cannot be done until the employee object has been created within the graph. Non-containment references need to be managed carefully. For example if the employee were now deleted from under the department, it would not be correct to try to save the graph without first clearing or re-assigning the employee_of_the_month property. The closure rule for SDO data graphs requires that any object pointed at by a non-containment reference must also be reachable by containment references.
When it comes to inserting the graph into the database, the procedure is similar to the example of inserting the company and department, but employee_of_the_month introduces an extra complexity. The Relational DAS needs to insert the objects working down the tree formed by containment references, so company, then department, then employee. This is necessary so that it always has the auto-generated primary key of a parent on hand to include in a child row. But when the company row is inserted the employee who is employee of the month has not yet been inserted and the primary key is not known. The procedure is that after the employee record is inserted and its primary key known, a final step is performed in which the the company record is updated with the employee's primary key.
<?php require_once 'SDO/DAS/Relational.php'; require_once 'company_metadata.inc.php'; /************************************************************************************* * Empty out the three tables *************************************************************************************/ $dbh = new PDO(PDO_DSN,DATABASE_USER,DATABASE_PASSWORD); $pdo_stmt = $dbh->prepare('DELETE FROM COMPANY;'); $rows_affected = $pdo_stmt->execute(); $pdo_stmt = $dbh->prepare('DELETE FROM DEPARTMENT;'); $rows_affected = $pdo_stmt->execute(); $pdo_stmt = $dbh->prepare('DELETE FROM EMPLOYEE;'); $rows_affected = $pdo_stmt->execute(); /************************************************************************************* * Create a tiny but complete company. * The company name is Acme. * There is one department, Shoe. * There is one employee, Sue. * The employee of the month is Sue. *************************************************************************************/ $das = new SDO_DAS_Relational ($database_metadata,'company',$SDO_reference_metadata); $dbh = new PDO(PDO_DSN,DATABASE_USER,DATABASE_PASSWORD); $root = $das -> createRootDataObject(); $acme = $root -> createDataObject('company'); $acme -> name = "Acme"; $shoe = $acme -> createDataObject('department'); $shoe -> name = 'Shoe'; $shoe -> location = 'A-block'; $sue = $shoe -> createDataObject('employee'); $sue -> name = 'Sue'; $acme -> employee_of_the_month = $sue; $das -> applyChanges($dbh, $root); echo "Wrote back Acme with one department and one employee\n"; ?>

Esempio 9. One company, one department, one employee - Retrieve and update
The SQL statement passed to the Relational DAS is this time an inner join that retrieves data from all three tables. Otherwise this example introduces nothing that has not appeared in a previous example.
The graph is updated by the addition of a new department and employee and some alterations to the name properties of the existing objects in the graph. The combined changes are then written back. The Relational DAS will process and apply an arbitrary mixture of additions, modifications and deletions to and from the data graph.
<?php require_once 'SDO/DAS/Relational.php'; require_once 'company_metadata.inc.php'; /************************************************************************************* * Find the company again and change various aspects. * Change the name of the company, department and employee. * Add a second department and a new employee. * Change the employee of the month. *************************************************************************************/ $das = new SDO_DAS_Relational ($database_metadata,'company',$SDO_reference_metadata); $dbh = new PDO(PDO_DSN,DATABASE_USER,DATABASE_PASSWORD); $root = $das->executeQuery($dbh, "select c.id, c.name, c.employee_of_the_month, d.id, d.name, e.id, e.name " . "from company c, department d, employee e " . "where e.dept_id = d.id and d.co_id = c.id and c.name='Acme'", array('company.id','company.name','company.employee_of_the_month', 'department.id','department.name','employee.id','employee.name')); $acme = $root['company'][0]; $shoe = $acme->department[0]; $sue = $shoe -> employee[0]; $it = $acme->createDataObject('department'); $it->name = 'IT'; $it->location = 'G-block'; $billy = $it->createDataObject('employee'); $billy->name = 'Billy'; $acme->name = 'MegaCorp'; $shoe->name = 'Footwear'; $sue->name = 'Susan'; $acme->employee_of_the_month = $billy; $das -> applyChanges($dbh, $root); echo "Wrote back company with extra department and employee and all the names changed (Megacorp/Footwear/Susan)\n"; ?>

Esempio 10. One company, two departments, two employees - Retrieve and delete
The company is retrieved as a complete data graph containing five data objects - the company, two departments and two employees. They are all deleted by deleting the company object. Deleting an object from the graph deletes all the object beneath it in the graph. Five SQL DELETE statements will be generated and executed. As always they will be qualified with a WHERE clause that contains all of the fields that were retrieved, so that any updates to the data in the database in the meantime by another process will be detected.
<?php require_once 'SDO/DAS/Relational.php'; require_once 'company_metadata.inc.php'; /************************************************************************************* * Now read it one more time and delete it. * You can delete part, apply the changes, then carry on working with the same graph but * care is needed to keep closure - you cannot delete the employee who is eotm without * reassigning. For safety here we delete the company all in one go. *************************************************************************************/ $das = new SDO_DAS_Relational ($database_metadata,'company',$SDO_reference_metadata); $dbh = new PDO(PDO_DSN,DATABASE_USER,DATABASE_PASSWORD); $root = $das->executeQuery($dbh, "select c.id, c.name, c.employee_of_the_month, d.id, d.name, e.id, e.name " . "from company c, department d, employee e " . "where e.dept_id = d.id and d.co_id = c.id and c.name='MegaCorp';", array('company.id','company.name','company.employee_of_the_month', 'department.id','department.name','employee.id','employee.name')); $megacorp = $root['company'][0]; unset($root['company']); $das -> applyChanges($dbh, $root); echo "Deleted the company, departments and employees all in one go.\n"; ?>

Tracing

You may be interested in seeing the SQL statements that are generated in order to apply changes back to the database. At the top of the SDO/DAS/Relational.php you will find a number of constants which control whether the process of constructing and executing the SQL statements is to be traced. Try setting DEBUG_EXECUTE_PLAN to TRUE to see the generated SQL statements.

Classi predefinite

The Relational DAS provides two classes: the Relational DAS itself and the subclass of Exception that can be thrown. The Relational DAS has four publicly useful calls: the constructor, the createRootDataObject() call to obtain the root object of an empty data graph, the executeQuery() call to obtain a data graph containing data from a relational database, and the applyChanges() call to write changes made to a data graph back to the relational database.

SDO_DAS_Relational

The only object other than an SDO_DAS_Relational_Exception with which the application is expected to interact.

Metodi

__construct - construct the Relational DAS with a model derived from the passed metadata
createRootDataObject - obtain an otherwise empty data graph containing just the special root object
executeQuery - execute an SQL query passed as a literal string and return the results as a normalised data graph
executePreparedQuery - execute an SQL query passed as a prepared statement, with a list of values to substitute for placeholders, and return the results as a normalised data graph
applyChanges - examine the change summary in the data graph and apply those changes back to the database, subject to an assumption of optimistic concurrency

SDO_DAS_Relational_Exception

Is a subclass of PHP's Exception. It adds no behaviour to Exception. Thrown, with useful descriptive text, to signal errors in the metadata or unexpected failures to perform SQL operations.

Sommario
SDO_DAS_Relational::applyChanges -- Applies the changes made to a data graph back to the database.
SDO_DAS_Relational::__construct -- Creates an instance of a Relational Data Access Service
SDO_DAS_Relational::createRootDataObject -- Returns the special root object in an otherwise empty data graph. Used when creating a data graph from scratch.
SDO_DAS_Relational::executePreparedQuery -- Executes an SQL query passed as a prepared statement, with a list of values to substitute for placeholders, and return the results as a normalised data graph.
SDO_DAS_Relational::executeQuery -- Executes a given SQL query against a relational database and returns the results as a normalised data graph.

SDO_DAS_Relational::applyChanges

(no version information, might be only in CVS)

SDO_DAS_Relational::applyChanges -- Applies the changes made to a data graph back to the database.

Descrizione

void SDO_DAS_Relational::applyChanges ( PDO database_handle, SDODataObject root_data_object )

Avvertimento

Given a PDO database handle and the special root object of a data graph, examine the change summary in the datagraph and applies the changes to the database. The changes that it can apply can be creations of data objects, deletes of data objects, and modifications to properties of data objects.

Elenco dei parametri

PDO_database_handle

Constructed using the PDO extension. A typical line to construct a PDO database handle might look like this:
$dbh = new PDO("mysql:dbname=COMPANYDB;host=localhost",DATABASE_USER,DATABASE_PASSWORD);

root_data_object

The special root object which is at the top of every SDO data graph.

Valori restituiti

None. Note however that the datagraph that was passed is still intact and usable. Furthermore, if data objects were created and written back to a table with autogenerated primary keys, then those primary keys will now be set in the data objects. If the changes were successfully written, then the change summary associated with the datagraph will have been cleared, so that it is possible to now make further changes to the data graph and apply those changes in turn. In this way it is possible to work with the same data graph and apply changes repeatedly.

Eccezioni

SDO_DAS_Relational::applyChanges() can throw an SDO_DAS_Relational_Exception if it is unable to apply all the changes correctly.

The Relational DAS starts a database transaction before beginning to apply the changes and will commit the transaction only if they are all successful. The Relational DAS generates qualified update and delete statements which contain a where clause that specifies that the row to be updated or deleted must contain the same values that it did when the data was first retrieved. This is how the the optimistic concurrency is implemented. If any of the qualified update or delete statements fails to update or delete their target row, it may be because the data has been altered in the database in the meantime. In any event, if any update fails for any reason, the transaction is rolled back and an exception thrown. The exception will contain the generated SQL statement that failed.

The Relational DAS also catches any PDO exceptions and obtains PDO diagnostic information which it includes in an SDO_DAS_Relational_Exception which it then throws.

Esempi

Please see the Examples section in the general information about the Relational DAS for many examples of calling this method. Please see also the section on Tracing to see how you can see what SQL statements are generated by the Relational DAS.

SDO_DAS_Relational::__construct

(no version information, might be only in CVS)

SDO_DAS_Relational::__construct -- Creates an instance of a Relational Data Access Service

Descrizione

SDO_DAS_Relational SDO_DAS_Relational::__construct ( array database_metadata [, string application_root_type [, array SDO_containment_references_metadata]] )

Avvertimento

Constructs an instance of a Relational Data Access Service from the passed metadata.

Elenco dei parametri

database_metadata: An array containing one or more table definitions, each of which is an associative array containing the keys name, columns, PK, and optionally, FK. For a full discussion of the metadata, see the metadata section in the general information about the Relational DAS.
application_root_type: The root of each data graph is an object of a special root type and the application data objects come below that. Of the various application types in the SDO model, one has to be the the application type immediately below the root of the data graph. If there is only one table in the database metadata, so the application root type can be inferred, this argument can be omitted.
SDO_containment_references_metadata: An array containing one or more definitions of a containment relation, each of which is an associative array containing the keys parent and child. The containment relations describe how the types in the model are connected to form a tree. The type specified as the application root type must be present as one of the parent types in the containment references. If the application only needs to work with one table at a time, and there are no containment relations in the model, this argument can be omitted. For a full discussion of the metadata, see the metadata section in the general information about the Relational DAS.

Valori restituiti

Returns an SDO_DAS_Relational object on success.

Eccezioni

SDO_DAS_Relational::__construct() throws a SDO_DAS_Relational_Exception if any problems are found in the metadata.

Esempi

For a full discussion of the metadata, see the metadata section in the general information about the Relational DAS.

SDO_DAS_Relational::createRootDataObject

(no version information, might be only in CVS)

SDO_DAS_Relational::createRootDataObject -- Returns the special root object in an otherwise empty data graph. Used when creating a data graph from scratch.

Descrizione

SDODataObject SDO_DAS_Relational::createRootDataObject ( void )

Avvertimento

Returns the special root object at the top of an otherwise empty data graph. This call is used when the application wants to create a data graph from scratch, without having called executeQuery() to create a data graph.

The special root object has one multi-valued containment property, with a name of the application root type that was passed when the Relational DAS was constructed. The property can take values of only that type. The only thing that the application can usefully do with the root type is to call createDataObject() on it, passing the name of the application root type, in order to create a data object of their own application type.

Elenco dei parametri

None.

Valori restituiti

The root object.

Eccezioni

None.

Esempi

Please see the Examples section in the general information about the Relational DAS for many examples of calling this method.

SDO_DAS_Relational::executePreparedQuery

(no version information, might be only in CVS)

SDO_DAS_Relational::executePreparedQuery -- Executes an SQL query passed as a prepared statement, with a list of values to substitute for placeholders, and return the results as a normalised data graph.

Descrizione

SDODataObject SDO_DAS_Relational::executePreparedQuery ( PDO database_handle, PDOStatement prepared_statement, array value_list [, array column_specifier] )

Avvertimento

Executes a given query against the relational database, using the supplied PDO database handle. Differs from the simpler executeQuery() in that it takes a prepared statement and a list of values. This is the appropriate call to use either when the statement is to executed a number of times with different arguments, and there is therefore a performance benefit to be had from preparing the statement only once, or when the the SQL statement is to contain varying values taken from a source that cannot be completely trusted. In this latter case it may be unsafe to construct the SQL statement by simply concatenating the parts of the statement together, since the values may contain pieces of SQL. To guard against this, a so-called SQL injection attack, it is safer to prepare the SQL statement with placeholders (also known as parameter markers, denoted by '?') and supply a list of the values to be substituted as a separate argument. Otherwise this function is the same as executeQuery() in that it uses the model that it built from the the metadata to interpret the result set and returns a data graph.

Elenco dei parametri

PDO_database_handle

Constructed using the PDO extension. A typical line to construct a PDO database handle might look like this:
$dbh = new PDO("mysql:dbname=COMPANYDB;host=localhost",DATABASE_USER,DATABASE_PASSWORD);

prepared_statement

A prepared SQL statement to be executed against the database. This will have been prepared by PDO's prepare() method.

value_list

An array of the values to be substituted into the SQL statement in place of the placeholders. In the event that there are no placeholders or parameter markers in the SQL statement then this argument can be specified as NULL or as an empty array;

column_specifier

The Relational DAS needs to examine the result set and for every column, know which table and which column of that table it came from. In some circumstances it can find this information for itself, but sometimes it cannot. In these cases a column specifier is needed, which is an array that identifies the columns. Each entry in the array is simply a string in the form table-name.column_name.

The column specifier is needed when there are duplicate column names in the database metadata, For example, in the database used within the examples, all the tables have both a id and a name column. When the Relational DAS fetches the result set from PDO it can do so with the PDO_FETCH_ASSOC attribute, which will cause the columns in the results set to be labelled with the column name, but will not distinguish duplicates. So this will only work when there are no duplicates possible in the results set.

To summarise, specify a column specifier array whenever there is any uncertainty about which column could be from which table and only omit it when every column name in the database metadata is unique.

All of the examples in the Examples use a column specifier. There is one example in the Scenarios directory of the installation that does not: that which works with just the employee table, and because it works with just one table, there can not exist duplicate column names.

Valori restituiti

Returns a data graph. Specifically, it returns a root object of a special type. Under this root object will be the data from the result set. The root object will have a multi-valued containment property with the same name as the application root type specified on the constructor, and that property will contain one or more data objects of the application root type.

In the event that the query returns no data, the special root object will still be returned but the containment property for the application root type will be empty.

Eccezioni

SDO_DAS_Relational::executeQuery() can throw an SDO_DAS_Relational_Exception if it is unable to construct the data graph correctly. This can occur for a number of reasons: for example if it finds that it does not have primary keys in the result set for all the objects. It also catches any PDO exceptions and obtains PDO diagnostic information which it includes in an SDO_DAS_Relational_Exception which it then throws.

Esempi

Esempio 1. Retrieving a data object using executePreparedQuery()
In this example a single data object is retrieved from the database - or possibly more than one if there is more than one company called 'Acme'. For each company returned, the name and id properties are echoed.
Other examples of the use of executePreparedQuery() can be found in the example code supplied in sdo/DAS/Relational/Scenarios .
<?php require_once 'SDO/DAS/Relational.php'; require_once 'company_metadata.inc.php'; /************************************************************** * Construct the DAS with the metadata ***************************************************************/ $das = new SDO_DAS_Relational ($database_metadata,'company',$SDO_reference_metadata); /************************************************************** * Get a database connection ***************************************************************/ $dbh = new PDO(PDO_DSN,DATABASE_USER,DATABASE_PASSWORD); /************************************************************** * Issue a query to obtain a company object - possibly more if they exist * Use a prepared query with a placeholder. ***************************************************************/ $name = 'Acme'; $pdo_stmt = $dbh->prepare('select name, id from company where name=?'); $root = $das->executePreparedQuery( $dbh, $pdo_stmt, array($name), array('company.name', 'company.id')); /************************************************************** * Echo name and id ***************************************************************/ foreach ($root['company'] as $company) { echo "Company obtained from the database has name = " . $company['name'] . " and id " . $company['id'] . "\n"; } ?>

SDO_DAS_Relational::executeQuery

(no version information, might be only in CVS)

SDO_DAS_Relational::executeQuery -- Executes a given SQL query against a relational database and returns the results as a normalised data graph.

Descrizione

SDODataObject SDO_DAS_Relational::executeQuery ( PDO database_handle, string SQL_statement [, array column_specifier] )

Avvertimento

Executes a given query against the relational database, using the supplied PDO database handle. Uses the model that it built from the the metadata to interpret the result set. Returns a data graph.

Elenco dei parametri

PDO_database_handle

Constructed using the PDO extension. A typical line to construct a PDO database handle might look like this:
$dbh = new PDO("mysql:dbname=COMPANYDB;host=localhost",DATABASE_USER,DATABASE_PASSWORD);

SQL_statement

The SQL statement to be executed against the database.

column_specifier

The column specifier is needed when there are duplicate column names in the database metadata. For example, in the database used within the examples, all the tables have both a id and a name column. When the Relational DAS fetches the result set from PDO it can do so with the PDO_FETCH_ASSOC attribute, which will cause the columns in the results set to be labelled with the column name, but will not distinguish duplicates. So this will only work when there are no duplicates possible in the results set.

Valori restituiti

In the event that the query returns no data, the special root object will still be returned but the containment property for the application root type will be empty.

Eccezioni

Esempi

Please see the Examples section in the general information about the Relational DAS for many examples of calling this method.

CXXXI. Funzioni per i semafori, la memoria condivisa ed IPC

Introduzione

Questo modulo fornisce le funzioni relative all'IPC di System V. Queste includono semafori, memoria condivisa e messaggi tra i processi (IPC).

I semafori possono essere utilizzati per fornire un accesso esclusivo alle risorse sulla macchina corrente, oppure per limitare il numero di processi che possono utilizzare simultaneamente una risorsa.

Questo modulo fornisce anche le funzioni per la memoria condivisa a partire dalla gestione della memoria condivisa di System V. La memoria condivisa può essere utilizzata per fornire l'accesso a variabili globali. Differenti demoni httpd e anche altri programmi (tipo Perl, C, ...) sono in grado di accedere a questi dati creando uno scambio di dati globale. Si ricordi che la memoria condivisa non è garantita nei confronti di accessi simultanei. Si utilizzino i semafori per la sincronizzazione.

Tabella 1. Limiti della memoria condivisa posti da UNIX

SHMMAX	dimensione massima della memoria condivisa, solitamente 131072 bytes
SHMMIN	dimensione minima della memoria condivisa, solitamente 1 byte
SHMMNI	massimo ammontare dei segmenti di memoria condivisa sul sistema, solitamente 100
SHMSEG	numero massimo di segmenti di memoria condivisa per processo, solitamente 6

Le funzioni relative ai messaggi possono essere usate per inviare e ricevere messaggi da/per altri processi. Esse permettono un semplice ed efficace metodo di interscambio dati tra i processi, senza dovere ricorrere ad alternative quali i socket nel dominio Unix.

Nota: Questo modulo non è disponibile su piattaforme Windows.

Requisiti

Non sono necessarie librerie esterne per utilizzare questo modulo.

Installazione

Di default non viene abilitato il supporto per queste funzioni. Per abilitare il supporto dei semafori di System V, compilare il PHP con l'opzione --enable-sysvsem. Per abilitare il supporto della memoria condivisa, compilare il PHP con l'opzione --enable-sysvshm. Per abilitare il supporto dei messaggi, compilare il PHP con l'opzione --enable-sysvmsg.

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

Tabella 2. Opzioni per la configurazione dei Semafori

Nome	Default	Modificabile	Variazioni
sysvmsg.value	"42"	PHP_INI_ALL
sysvmsg.string	"foobar"	PHP_INI_ALL

Per maggiori dettagli sulle costanti PHP_INI_* vedere Appendice G.

Tipi di risorse

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

Tabella 3. Costanti per i messaggi System V

Costante	Tipo
MSG_IPC_NOWAIT	integer
MSG_NOERROR	integer
MSG_EXCEPT	integer

Sommario
ftok -- Converte il percorso e un identificatore di progetto in un chiave IPC di System V
msg_get_queue -- Crea, o si collega ad una coda di messaggi
msg_receive -- Riceve un messaggio da una coda
msg_remove_queue -- Distrugge una coda di messaggi
msg_send -- Invia un messaggio ad una coda di messaggi
msg_set_queue -- Valorizza le informazioni nella struttura dati della coda dei messaggi
msg_stat_queue -- Restituisce informazioni dalla struttura dati della coda
sem_acquire -- Acquisisce un semaforo
sem_get -- Ottiene l'id di un semaforo
sem_release -- Rilascia un semaforo
sem_remove -- Rimuove un semaforo
shm_attach -- Crea oppure apre un segmento di memoria condivisa
shm_detach -- Disconnette da un segmento di memoria condivisa
shm_get_var -- Restituisce una variabile dalla memoria condivisa
shm_put_var -- Inserisce o aggiorna una variabile nella memoria condivisa
shm_remove_var -- Rimuove una variabile dalla memoria condivisa
shm_remove -- Rimuove un segmento di memoria condivisa dal sistema Unix

ftok

(PHP 4 >= 4.2.0, PHP 5)

ftok -- Converte il percorso e un identificatore di progetto in un chiave IPC di System V

Descrizione

int ftok ( string pathname, string proj )

La funzione converte il parametro pathname di un file accessibile e l'identificatore di un progetto (proj) in un numero interger da utilizzare, ad esempio, con shmop_open() e le altre chiavi IPC di System V. Il parametro proj dovrebbe essere una stringa di un carattere.

Se la funzione riesce sarà restituito il valore della chiave creata, altrimenti si restituirà -1.

Vedere anche: shmop_open() e sem_get().

msg_get_queue

(PHP 4 >= 4.3.0, PHP 5)

msg_get_queue -- Crea, o si collega ad una coda di messaggi

Descrizione

resource msg_get_queue ( int chiave [, int permessi] )

La funzione msg_get_queue() restituisce un id che può essere utilizzato per accedere alla coda dei messaggi System V con la data chiave. La prima chiamata crea la coda dei messaggi con i permessi indicati da permessi (default: 0666). La seconda chiamata alla funzione msg_get_queue() per la medesima chiave restituirà un identificatore di coda di messaggi differente, ma entrambi accederanno alla medesima coda di messaggi. Se la coda dei messaggi esiste già, il parametro permessi sarà ignorato.

Vedere anche: msg_remove_queue(), msg_receive(), msg_send(), msg_stat_queue() e msg_set_queue().

msg_receive

(PHP 4 >= 4.3.0, PHP 5)

msg_receive -- Riceve un messaggio da una coda

Descrizione

bool msg_receive ( resource coda, int tipo_desiderato, int &tipo_messaggio, int dimensione_max, mixed &messaggio [, bool unserialize [, int flags [, int codice_errore [, int &codice_errore]]]] )

La funzione msg_receive() riceve il primo messaggio dalla coda specificata in coda del tipo indicato in tipo_desiderato. Il tipo di messaggio che è stato ricevuto viene memorizzato in tipo_messaggio. La dimensione massima del messaggio accettata viene indicata in dimensione_max; se il messaggio nella coda è più grande, la funzione darà esito negativo (a meno che non sia impostato il parametro flags come descritto in seguito). Il messaggio ricevuto sarà memorizzato in messaggio, a meno che non si verifichino degli errori in ricezione, in tal caso il parametro opzionale errorcode sarà valorizzato con il valore della variabile errno per aiutare ad identificare la causa.

Se il parametro tipo_desiderato è 0, verrà restituito il primo messaggio dalla coda. Se, invece, tipo_desiderato è maggiore di 0, sarà restuito il primo messaggio di quel tipo. Mentre se tipo_desiderato è minore di 0, sarà restituito dalla coda il primo messaggio con il tipo più basso o uguale al valore assoluto di tipo_desiderato. Se nessun messaggio soddisfa i criteri impostati, lo script attenderà fino all'arrivo nella coda di un messaggio adeguato. Si può evitare il blocco dello script indicando MSG_IPC_NOWAIT nel parametro flags.

Il parametro unserialize (default TRUE), se viene impostato a TRUE indica di trattare il messaggio come se fosse serializzato utilizzando lo stesso meccanismo del modulo delle sessioni. In tal modo il messaggio può essere deserializzato e restituito allo script. Questo permette di ricevere facilmente array o complesse strutture oggetto da altri script PHP, o, se si sta utilizzando il serializzatore WDDX, da sorgenti compatibili con WDDX. Se unserialize è impostato a FALSE, il messaggio sarà restituito come una stringa.

Il parametro opzionale flags permette di passare flag alla chiamata di sistema msgrcv. Il default è 0, ma possono essere specificati uno o più dei seguenti valori (sommandoli o legandoli con OR).

Tabella 1. Valori dei flag per msg_receive

`MSG_IPC_NOWAIT`	Se non ci sono messaggi del `tipo_desiderato`, la funzione ritorna immediatamente senza aspettare. La funzione fallirà e restituirà un valore intero corrispondente a ENOMSG.
`MSG_EXCEPT`	Usando questo flag in combinazione con `tipo_desiderato` maggiore di 0, si forza la funzione a ricevere il primo messaggio che non sia uguale a `tipo_desiderato`.
`MSG_NOERROR`	Se il messaggio è più lungo di `dimensione_max`, l'attivazione di questo flag troncherà il messaggio a `dimensione_max` e non sarà segnalato alcun errore.

Una volta eseguita con successo la ricezione, la struttura dati della coda dei messaggi verrà aggiornata come segue: msg_lrpid sarà impostato all'ID di processo del processo chiamante, msg_qnum verrà decrementato di 1 e msg_rtime sarà impostato all'ora corrente.

La funzione msg_receive() restituisce TRUE se ha successo oppure FALSE se non riesce. Se la funzione fallisce, il parametro opzionale codice_errore verrà impostato al valore della variabile errno.

Vedere anche: msg_remove_queue(), msg_send(), msg_stat_queue() e msg_set_queue().

msg_remove_queue

(PHP 4 >= 4.3.0, PHP 5)

msg_remove_queue -- Distrugge una coda di messaggi

Descrizione

bool msg_remove_queue ( resource coda )

La funzione msg_remove_queue() rimuove la coda di messaggi specificata dal parametro coda. Si utilizzi questa funzione solo quando tutti i processi hanno terminato di lavorare con la coda dei messaggi e si ha la necessità di rilasciare le risorse di sistema occupate.

Vedere anche: msg_get_queue(), msg_receive(), msg_stat_queue() e msg_set_queue().

msg_send

(PHP 4 >= 4.3.0, PHP 5)

msg_send -- Invia un messaggio ad una coda di messaggi

Descrizione

bool msg_send ( resource coda, int tipo_messaggio, mixed messaggio [, bool serialize [, bool blocco [, int &codice_errore]]] )

La funzione msg_send() invia il messaggio di tipo tipo_messaggio (che DEVE essere maggiore di 0) ad una coda di messaggi indicata in coda.

Se il messaggio è troppo grande per essere contenuto nella coda, lo script attenderà fino a quando un'altro processo, leggendo i messaggi dalla coda, non libera lo spazio necessario per il messaggio da inviare. Questo viene detto blocco; si può prevenire il blocco indicando nel parametro opzionale blocco il valore FALSE, in questo caso msg_send() restituirà immediatamente FALSE se il messaggio è troppo grande per la coda, e impostando il parametro opzionale codice_errore a EAGAIN, si indica di ritentare l'invio del messaggio dopo poco tempo.

Il parametro opzionale serialize controlla come inviare il messaggio. serialize, quando è impostato al valore di default TRUE, indica che il messaggio, prima di essere inviato alla coda, deve essere serializzato utilizzando il medesimo meccanismo del modulo delle sessioni. Questo permette ad array complessi o ad oggetti di essere inviati ad altri script PHP, oppure, se si sta usando il modulo di serializzazione di WDDX, di essere inviati a client compatibili con WDDX.

Una volta eseguito con successo l'invio, la struttura dati della coda dei messaggi viene aggiornata come segue: msg_lspid viene impostato all'ID di processo del processo chiamante, msg_qnum viene incrementato di 1 e msg_stime viene impostato all'ora corrente.

Vedere anche: msg_remove_queue(), msg_receive(), msg_stat_queue() e msg_set_queue().

msg_set_queue

(PHP 4 >= 4.3.0, PHP 5)

msg_set_queue -- Valorizza le informazioni nella struttura dati della coda dei messaggi

Descrizione

bool msg_set_queue ( resource coda, array dati )

msg_set_queue() permette di modificare i valori dei campi msg_perm.uid, msg_perm.gid, msg_perm.mode e msg_qbytes della sottostante struttura dati della coda. Per specificare il valore, occorre impostare il valore nella chiave dell'array dati che si desidera modificare.

Per potere cambiare la struttura dati occorre che il PHP sia eseguito con lo stesso utente che ha creato la coda, sia proprietario della coda (code determinato dal campo msg_perm.xxx), o sia eseguito con i privilegi di root. Sono richiesti i privilegi di root per potere aumentare msg_qbytes a valori superiori ai limiti definiti dal sistema.

Vedere anche: msg_remove_queue(), msg_receive(), msg_stat_queue() e msg_get_queue().

msg_stat_queue

(PHP 4 >= 4.3.0, PHP 5)

msg_stat_queue -- Restituisce informazioni dalla struttura dati della coda

Descrizione

array msg_stat_queue ( resource coda )

msg_stat_queue() restituisce i dati della coda dei messaggi indicata in coda. Questo può essere utile, ad esempio, per determinare quale processo ha inviato il messaggio che è stato appena ricevuto.

Il valore restituito è un array le cui chiavi e valori hanno il seguente significato:

Tabella 1. Struttura dell'array di msg_stat_queue

`msg_perm.uid`	Il parametro uid del proprietario della coda
`msg_perm.gid`	Il parametro gid del proprietario della coda.
`msg_perm.mode`	La modalità di accesso alla coda.
`msg_stime`	L'orario in cui è stato inserito in coda l'ultimo messaggio.
`msg_rtime`	L'orario in cui l'ultimo messaggio è stato ricevuto dalla coda.
`msg_ctime`	L'orario in cui è avvenuta l'ultima modifica alla coda.
`msg_qnum`	Il numero di messaggi in attesa di essere letti dalla coda.
`msg_qbytes`	Il numero di byte dello spazio attualemnet disponibile nella coda per trattenere i messaggi fino a quando non sono ricevuti.
`msg_lspid`	Il pid del processo che ha inviato l'ultimo messaggio.
`msg_lrpid`	Il pid del processo che ha ricevuto l'ultimo messaggio dalla coda.

Vedere anche: msg_remove_queue(), msg_receive(), msg_get_queue() e msg_set_queue().

sem_acquire

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

sem_acquire -- Acquisisce un semaforo

Descrizione

bool sem_acquire ( resource sem_identifier )

La funzione sem_acquire() si blocca (se necessario) fino a quando non riesce ad acquisire il semaforo. Se un processo tenta di acquisire un semaforo che ha già acquisito può restare bloccato per sempre se la nuova acquisizione del semaforo causa il superamento del numero massimo di semafori consentito. sem_identifier è una risorsa semaforo ottenuta da sem_get().

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Dopo avere processato una richiesta, qualsiasi semaforo acquisito dal processo, ma non esplicitamente rilasciato, sarà rilasciato automaticamente e causerà un messaggio di warning.

Vedere anche: sem_get() e sem_release().

sem_get

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

sem_get -- Ottiene l'id di un semaforo

Descrizione

resource sem_get ( int key [, int max_acquire [, int perm [, int auto_release]]] )

mixed shm_get_var ( int shm_identifier, int variable_key )

La funzione shm_get_var() restituisce la variabile identificata dalla chiave variable_key, da un segmento di memoria condivisa identificato tramite shm_identifier. La variabile resta presente nella memoria condivisa.

shm_put_var

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

shm_put_var -- Inserisce o aggiorna una variabile nella memoria condivisa

Descrizione

bool shm_put_var ( int shm_identifier, int variable_key, mixed variable )

La funzione shm_put_var() inserisce o aggiorna la variabile indicata in variable con chiave variable_key. Sono suportati Tutti i tipi di variabili sono supportati.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Verrà generato un warning (E_WARNING level) se il parametro shm_identifier non è un puntatore valido ad un segmento di memoria condivisa SysV oppure se non vi è sufficiente memoria condivisa per completare la richiesta.

shm_remove_var

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

shm_remove_var -- Rimuove una variabile dalla memoria condivisa

Descrizione

int shm_remove_var ( int shm_identifier, int variable_key )

Rimuove la variabile identificata da variable_key e libera la memoria occupata.

Vedere anche shm_remove().

shm_remove

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

shm_remove -- Rimuove un segmento di memoria condivisa dal sistema Unix

Descrizione

int shm_remove ( int shm_identifier )

La funzione shm_remove() rimuove un segmento di memoria condivisa identificata da shm_identifier. Tutti i dati contenuti saranno persi.

Vedere anche shm_remove_var().

CXXXII. SESAM Database Functions

Introduzione

SESAM/SQL-Server is a mainframe database system, developed by Fujitsu Siemens Computers, Germany. It runs on high-end mainframe servers using the operating system BS2000/OSD.

In numerous productive BS2000 installations, SESAM/SQL-Server has proven

the ease of use of Java-, Web- and client/server connectivity,
the capability to work with an availability of more than 99.99%,
the ability to manage tens and even hundreds of thousands of users.

There is a PHP 3 SESAM interface available which allows database operations via PHP-scripts.

Nota: Access to SESAM is only available with the latest CVS-Version of PHP 3. PHP 4 does not support the SESAM database.

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

sesam_oml string

Name of BS2000 PLAM library containing the loadable SESAM driver modules. Required for using SESAM functions. The BS2000 PLAM library must be set ACCESS=READ,SHARE=YES because it must be readable by the apache server's user id.

sesam_configfile string

Name of SESAM application configuration file. Required for using SESAM functions. The BS2000 file must be readable by the apache server's user id.

The application configuration file will usually contain a configuration like (see SESAM reference manual):

CNF=B
NAM=K
NOTYPE

sesam_messagecatalog string

Name of SESAM message catalog file. In most cases, this directive is not necessary. Only if the SESAM message file is not installed in the system's BS2000 message file table, it can be set with this directive.

The message catalog must be set ACCESS=READ,SHARE=YES because it must be readable by the apache server's user id.

Configuration notes

There is no standalone support for the PHP SESAM interface, it works only as an integrated Apache module. In the Apache PHP module, this SESAM interface is configured using Apache directives.

Tabella 1. SESAM Configuration directives

Directive

Meaning

php3_sesam_oml

Name of BS2000 PLAM library containing the loadable SESAM driver modules. Required for using SESAM functions.

Example:

php3_sesam_oml $.SYSLNK.SESAM-SQL.030

php3_sesam_configfile

Name of SESAM application configuration file. Required for using SESAM functions.

Example:

php3_sesam_configfile $SESAM.SESAM.CONF.AW

It will usually contain a configuration like (see SESAM reference manual):

CNF=B
NAM=K
NOTYPE

php3_sesam_messagecatalog

Example:

php3_sesam_messagecatalog $.SYSMES.SESAM-SQL.030

In addition to the configuration of the PHP/SESAM interface, you have to configure the SESAM-Database server itself on your mainframe as usual. That means:

starting the SESAM database handler (DBH), and
connecting the databases with the SESAM database handler

To get a connection between a PHP script and the database handler, the CNF and NAM parameters of the selected SESAM configuration file must match the id of the started database handler.

In case of distributed databases you have to start a SESAM/SQL-DCN agent with the distribution table including the host and database names.

The communication between PHP (running in the POSIX subsystem) and the database handler (running outside the POSIX subsystem) is realized by a special driver module called SQLSCI and SESAM connection modules using common memory. Because of the common memory access, and because PHP is a static part of the web server, database accesses are very fast, as they do not require remote accesses via ODBC, JDBC or UTM.

Only a small stub loader (SESMOD) is linked with PHP, and the SESAM connection modules are pulled in from SESAM's OML PLAM library. In the configuration, you must tell PHP the name of this PLAM library, and the file link to use for the SESAM configuration file (As of SESAM V3.0, SQLSCI is available in the SESAM Tool Library, which is part of the standard distribution).

Because the SQL command quoting for single quotes uses duplicated single quotes (as opposed to a single quote preceded by a backslash, used in some other databases), it is advisable to set the PHP configuration directives php3_magic_quotes_gpc and php3_magic_quotes_sybase to On for all PHP scripts using the SESAM interface.

Runtime considerations

Because of limitations of the BS2000 process model, the driver can be loaded only after the Apache server has forked off its server child processes. This will slightly slow down the initial SESAM request of each child, but subsequent accesses will respond at full speed.

When explicitly defining a Message Catalog for SESAM, that catalog will be loaded each time the driver is loaded (i.e., at the initial SESAM request). The BS2000 operating system prints a message after successful load of the message catalog, which will be sent to Apache's error_log file. BS2000 currently does not allow suppression of this message, it will slowly fill up the log.

Make sure that the SESAM OML PLAM library and SESAM configuration file are readable by the user id running the web server. Otherwise, the server will be unable to load the driver, and will not allow to call any SESAM functions. Also, access to the database must be granted to the user id under which the Apache server is running. Otherwise, connections to the SESAM database handler will fail.

Cursor Types

The result cursors which are allocated for SQL "select type" queries can be either "sequential" or "scrollable". Because of the larger memory overhead needed by "scrollable" cursors, the default is "sequential".

When using "scrollable" cursors, the cursor can be freely positioned on the result set. For each "scrollable" query, there are global default values for the scrolling type (initialized to: SESAM_SEEK_NEXT) and the scrolling offset which can either be set once by sesam_seek_row() or each time when fetching a row using sesam_fetch_row(). When fetching a row using a "scrollable" cursor, the following post-processing is done for the global default values for the scrolling type and scrolling offset:

Tabella 2. Scrolled Cursor Post-Processing

Scroll Type	Action
`SESAM_SEEK_NEXT`	none
`SESAM_SEEK_PRIOR`	none
`SESAM_SEEK_FIRST`	set scroll type to `SESAM_SEEK_NEXT`
`SESAM_SEEK_LAST`	set scroll type to `SESAM_SEEK_PRIOR`
`SESAM_SEEK_ABSOLUTE`	Auto-Increment internal offset value
`SESAM_SEEK_RELATIVE`	none. (maintain global default `offset` value, which allows for, e.g., fetching each 10th row backwards)

Porting note

Because in the PHP world it is natural to start indexes at zero (rather than 1), some adaptions have been made to the SESAM interface: whenever an indexed array is starting with index 1 in the native SESAM interface, the PHP interface uses index 0 as a starting point. E.g., when retrieving columns with sesam_fetch_row(), the first column has the index 0, and the subsequent columns have indexes up to (but not including) the column count ($array["count"]). When porting SESAM applications from other high level languages to PHP, be aware of this changed interface. Where appropriate, the description of the respective PHP sesam functions include a note that the index is zero based.

Security concerns

When allowing access to the SESAM databases, the web server user should only have as little privileges as possible. For most databases, only read access privilege should be granted. Depending on your usage scenario, add more access rights as you see fit. Never allow full control to any database for any user from the 'net! Restrict access to PHP scripts which must administer the database by using password control and/or SSL security.

Migration from other SQL databases

No two SQL dialects are ever 100% compatible. When porting SQL applications from other database interfaces to SESAM, some adaption may be required. The following typical differences should be noted:

Vendor specific data types
Some vendor specific data types may have to be replaced by standard SQL data types (e.g., TEXT could be replaced by VARCHAR(max. size)).
Keywords as SQL identifiers
In SESAM (as in standard SQL), such identifiers must be enclosed in double quotes (or renamed).
Display length in data types
SESAM data types have a precision, not a display length. Instead of int(4) (intended use: integers up to '9999'), SESAM requires simply int for an implied size of 31 bits. Also, the only datetime data types available in SESAM are: DATE, TIME(3) and TIMESTAMP(3).
SQL types with vendor-specific unsigned, zerofill, or auto_increment attributes
Unsigned and zerofill are not supported. Auto_increment is automatic (use "INSERT ... VALUES(*, ...)" instead of "... VALUES(0, ...)" to take advantage of SESAM-implied auto-increment.
int ... DEFAULT '0000'
Numeric variables must not be initialized with string constants. Use DEFAULT 0 instead. To initialize variables of the datetime SQL data types, the initialization string must be prefixed with the respective type keyword, as in: CREATE TABLE exmpl ( xtime timestamp(3) DEFAULT TIMESTAMP '1970-01-01 00:00:00.000' NOT NULL );
$count = xxxx_num_rows();
Some databases promise to guess/estimate the number of the rows in a query result, even though the returned value is grossly incorrect. SESAM does not know the number of rows in a query result before actually fetching them. If you REALLY need the count, try SELECT COUNT(...) WHERE ..., it will tell you the number of hits. A second query will (hopefully) return the results.
DROP TABLE thename;
In SESAM, in the DROP TABLE command, the table name must be either followed by the keyword RESTRICT or CASCADE. When specifying RESTRICT, an error is returned if there are dependent objects (e.g., VIEWs), while with CASCADE, dependent objects will be deleted along with the specified table.

Notes on the use of various SQL types

SESAM does not currently support the BLOB type. A future version of SESAM will have support for BLOB.

At the PHP interface, the following type conversions are automatically applied when retrieving SQL fields:

Tabella 3. SQL to PHP Type Conversions

SQL Type	PHP Type
SMALLINT, INTEGER	integer
NUMERIC, DECIMAL, FLOAT, REAL, DOUBLE	float
DATE, TIME, TIMESTAMP	string
VARCHAR, CHARACTER	string

When retrieving a complete row, the result is returned as an array. Empty fields are not filled in, so you will have to check for the existence of the individual fields yourself (use isset() or empty() to test for empty fields). That allows more user control over the appearance of empty fields (than in the case of an empty string as the representation of an empty field).

Support of SESAM's "multiple fields" feature

The special "multiple fields" feature of SESAM allows a column to consist of an array of fields. Such a "multiple field" column can be created like this:
Esempio 1. Creating a "multiple field" column
CREATE TABLE multi_field_test ( pkey CHAR(20) PRIMARY KEY, multi(3) CHAR(12) )
and can be filled in using:
Esempio 2. Filling a "multiple field" column
INSERT INTO multi_field_test (pkey, multi(2..3) ) VALUES ('Second', <'first_val', 'second_val'>)
Note that (like in this case) leading empty sub-fields are ignored, and the filled-in values are collapsed, so that in the above example the result will appear as multi(1..2) instead of multi(2..3).

When retrieving a result row, "multiple columns" are accessed like "inlined" additional columns. In the example above, "pkey" will have the index 0, and the three "multi(1..3)" columns will be accessible as indices 1 through 3.

Vedere anche:

For specific SESAM details, please refer to the SESAM/SQL-Server documentation (english) or the SESAM/SQL-Server documentation (german), both available online, or use the respective manuals.

Sommario
sesam_affected_rows -- Get number of rows affected by an immediate query
sesam_commit -- Commit pending updates to the SESAM database
sesam_connect -- Open SESAM database connection
sesam_diagnostic -- Return status information for last SESAM call
sesam_disconnect -- Detach from SESAM connection
sesam_errormsg -- Returns error message of last SESAM call
sesam_execimm -- Execute an "immediate" SQL-statement
sesam_fetch_array -- Fetch one row as an associative array
sesam_fetch_result -- Return all or part of a query result
sesam_fetch_row -- Fetch one row as an array
sesam_field_array -- Return meta information about individual columns in a result
sesam_field_name -- Return one column name of the result set
sesam_free_result -- Releases resources for the query
sesam_num_fields -- Return the number of fields/columns in a result set
sesam_query -- Perform a SESAM SQL query and prepare the result
sesam_rollback -- Discard any pending updates to the SESAM database
sesam_seek_row -- Set scrollable cursor mode for subsequent fetches
sesam_settransaction -- Set SESAM transaction parameters

The "user" argument references one of the users which are allowed to access this "catalog" / "schema" combination. Note that "user" is completely independent from both the system's user id's and from HTTP user/password protection. It appears in the SESAM configuration only.

See also sesam_disconnect().
Esempio 1. Connect to a SESAM database
<?php if (!sesam_connect ("mycatalog", "myschema", "otto")) { die("Unable to connect to SESAM"); } ?>

sesam_diagnostic

(PHP 3 CVS only)

sesam_diagnostic -- Return status information for last SESAM call

Description

array sesam_diagnostic ( void )

Returns an associative array of status and return codes for the last SQL query/statement/command. Elements of the array are:

Tabella 1. Status information returned by sesam_diagnostic()

Element	Contents
$array["sqlstate"]	5 digit SQL return code (see the SESAM manual for the description of the possible values of SQLSTATE)
$array["rowcount"]	number of affected rows in last update/insert/delete (set after "immediate" statements only)
$array["errmsg"]	"human readable" error message string (set after errors only)
$array["errcol"]	error column number of previous error (0-based; or -1 if undefined. Set after errors only)
$array["errlin"]	error line number of previous error (0-based; or -1 if undefined. Set after errors only)

In the following example, a syntax error (E SEW42AE ILLEGAL CHARACTER) is displayed by including the offending SQL statement and pointing to the error location:
Esempio 1. Displaying SESAM error messages with error position
<?php // Function which prints a formatted error message, // displaying a pointer to the syntax error in the // SQL statement function PrintReturncode($exec_str) { $err = Sesam_Diagnostic(); $colspan=4; // 4 cols for: sqlstate, errlin, errcol, rowcount if ($err["errlin"] == -1) --$colspan; if ($err["errcol"] == -1) --$colspan; if ($err["rowcount"] == 0) --$colspan; echo "<table border=\"1\">\n"; echo "<tr><th colspan=\"" . $colspan . "\"><span class=\"spanred\">ERROR:</span> ". htmlspecialchars($err["errmsg"]) . "</th></tr>\n"; if ($err["errcol"] >= 0) { echo "<tr><td colspan=\"" . $colspan . "\"><pre>\n"; $errstmt = $exec_str . "\n"; for ($lin=0; $errstmt != ""; ++$lin) { if ($lin != $err["errlin"]) { // $lin is less or greater than errlin if (!($i = strchr($errstmt, "\n"))) $i = ""; $line = substr ($errstmt, 0, strlen($errstmt)-strlen($i)+1); $errstmt = substr($i, 1); if ($line != "\n") echo htmlspecialchars($line); } else { if (! ($i = strchr ($errstmt, "\n"))) $i = ""; $line = substr ($errstmt, 0, strlen ($errstmt)-strlen($i)+1); $errstmt = substr($i, 1); for ($col=0; $col < $err["errcol"]; ++$col) { echo (substr($line, $col, 1) == "\t") ? "\t" : "."; } echo "<span class=\"spanred\">\\</span>\n"; echo "<span class=\"normal\">" . htmlspecialchars($line) . "</span>"; for ($col=0; $col < $err["errcol"]; ++$col) { echo (substr ($line, $col, 1) == "\t") ? "\t" : "."; } echo "<span class=\"spanred\">/</span>\n"; } } echo "</pre></td></tr>\n"; } echo "<tr>\n"; echo " <td>sqlstate=" . $err["sqlstate"] . "</td>\n"; if ($err["errlin"] != -1) echo " <td>errlin=" . $err["errlin"] . "</td>\n"; if ($err["errcol"] != -1) echo " <td>errcol=" . $err["errcol"] . "</td>\n"; if ($err["rowcount"] != 0) echo " <td>rowcount=" . $err["rowcount"] . "</td>\n"; echo "</tr>\n"; echo "</table>\n"; } if (!sesam_connect ("mycatalog", "phoneno", "otto")) die ("cannot connect"); $stmt = "SELECT * FROM phone\n" . " WHERE@ LASTNAME='KRAEMER'\n" . " ORDER BY FIRSTNAME"; if (!($result = sesam_query ($stmt))) PrintReturncode ($stmt); ?>

See also: sesam_errormsg() for simple access to the error string only

sesam_disconnect

(PHP 3 CVS only)

sesam_disconnect -- Detach from SESAM connection

Description

bool sesam_disconnect ( void )

Returns: always TRUE.

sesam_disconnect() closes the logical link to a SESAM database (without actually disconnecting and unloading the driver).

Note that this isn't usually necessary, as the open connection is automatically closed at the end of the script's execution. Uncommitted data will be discarded, because an implicit sesam_rollback() is executed.

sesam_disconnect() will not close the persistent link, it will only invalidate the currently defined "catalog", "schema" and "user" triple, so that any sesam function called after sesam_disconnect() will fail.

Esempio 1. Closing a SESAM connection
<?php if (sesam_connect ("mycatalog", "myschema", "otto")) { /* ... some queries and stuff ... */ sesam_disconnect(); } ?>

sesam_errormsg

(PHP 3 CVS only)

sesam_errormsg -- Returns error message of last SESAM call

Description

string sesam_errormsg ( void )

Returns the SESAM error message associated with the most recent SESAM error.

Esempio 1. sesam_errormsg() example
<?php if (!sesam_execimm($stmt)) { echo sesam_errormsg() . "<br />\n"; } ?>

See also sesam_diagnostic() for the full set of SESAM SQL status information.

sesam_execimm

(PHP 3 CVS only)

sesam_execimm -- Execute an "immediate" SQL-statement

Description

string sesam_execimm ( string query )

Returns: A SESAM "result identifier" on success, or FALSE on error.

sesam_execimm() executes an "immediate" statement (i.e., a statement like UPDATE, INSERT or DELETE which returns no result, and has no INPUT or OUTPUT variables). "select type" queries can not be used with sesam_execimm(). Sets the affected_rows value for retrieval by the sesam_affected_rows() function.

Note that sesam_query() can handle both "immediate" and "select-type" queries. Use sesam_execimm() only if you know beforehand what type of statement will be executed. An attempt to use SELECT type queries with sesam_execimm() will return $err["sqlstate"] == "42SBW".

The returned "result identifier" can not be used for retrieving anything but the sesam_affected_rows(); it is only returned for symmetry with the sesam_query() function.

<?php
$stmt = "INSERT INTO mytable VALUES ('one', 'two')";
$result = sesam_execimm($stmt);
$err = sesam_diagnostic();
echo "sqlstate = " . $err["sqlstate"] . "\n".
       "Affected rows = " . $err["rowcount"] . " == " .
       sesam_affected_rows($result) . "\n";
?>

sesam_fetch_array

(PHP 3 CVS only)

sesam_fetch_array -- Fetch one row as an associative array

Description

array sesam_fetch_array ( string result_id [, int whence [, int offset]] )

Returns an array that corresponds to the fetched row, or FALSE if there are no more rows.

sesam_fetch_array() is an alternative version of sesam_fetch_row(). Instead of storing the data in the numeric indices of the result array, it stores the data in associative indices, using the field names as keys.

result_id is a valid result id returned by sesam_query() (select type queries only!).

For the valid values of the optional whenceand offset parameters, see the sesam_fetch_row() function for details.

sesam_fetch_array() fetches one row of data from the result associated with the specified result identifier. The row is returned as an associative array. Each result column is stored with an associative index equal to its column (aka. field) name. The column names are converted to lower case.

Columns without a field name (e.g., results of arithmetic operations) and empty fields are not stored in the array. Also, if two or more columns of the result have the same column names, the later column will take precedence. In this situation, either call sesam_fetch_row() or make an alias for the column.

SELECT TBL1.COL AS FOO, TBL2.COL AS BAR FROM TBL1, TBL2

A special handling allows fetching "multiple field" columns (which would otherwise all have the same column names). For each column of a "multiple field", the index name is constructed by appending the string "(n)" where n is the sub-index of the multiple field column, ranging from 1 to its declared repetition factor. The indices are NOT zero based, in order to match the nomenclature used in the respective query syntax. For a column declared as:

CREATE TABLE ... ( ... MULTI(3) INT )

the associative indices used for the individual "multiple field" columns would be "multi(1)", "multi(2)", and "multi(3)" respectively.

Subsequent calls to sesam_fetch_array() would return the next (or prior, or n'th next/prior, depending on the scroll attributes) row in the result set, or FALSE if there are no more rows.

Esempio 1. SESAM fetch array

<?php
$result = sesam_query("SELECT * FROM phone\n" .
                       "  WHERE LASTNAME='" . strtoupper($name) . "'\n".
                       "  ORDER BY FIRSTNAME", 1);
if (!$result) {
    /* ... error ... */
}
// print the table:
echo "<table border=\"1\">\n";
while (($row = sesam_fetch_array($result)) && count($row) > 0) {
    echo "<tr>\n";
    echo "<td>" . htmlspecialchars($row["firstname"]) . "</td>\n";
    echo "<td>" . htmlspecialchars($row["lastname"]) . "</td>\n";
    echo "<td>" . htmlspecialchars($row["phoneno"]) . "</td>\n";
    echo "</tr>\n";
}
echo "</table>\n";
sesam_free_result($result);
?>

See also: sesam_fetch_row() which returns an indexed array.

sesam_fetch_result

(PHP 3 CVS only)

sesam_fetch_result -- Return all or part of a query result

Description

mixed sesam_fetch_result ( string result_id [, int max_rows] )

Returns a mixed array with the query result entries, optionally limited to a maximum of max_rows rows. Note that both row and column indexes are zero-based.

Tabella 1. Mixed result set returned by sesam_fetch_result()

Array Element	Contents
int $arr["count"]	number of columns in result set (or zero if this was an "immediate" query)
int $arr["rows"]	number of rows in result set (between zero and `max_rows`)
bool $arr["truncated"]	`TRUE` if the number of rows was at least `max_rows`, `FALSE` otherwise. Note that even when this is `TRUE`, the next sesam_fetch_result() call may return zero rows because there are no more result entries.
mixed $arr[col][row]	result data for all the fields at row(`row`) and column(`col`), (where the integer index `row` is between 0 and `$arr["rows"]-1`, and `col` is between 0 and `$arr["count"]-1`). Fields may be empty, so you must check for the existence of a field by using the php isset() function. The type of the returned fields depend on the respective SQL type declared for its column (see SESAM overview for the conversions applied). SESAM "multiple fields" are "inlined" and treated like a sequence of columns.

Note that the amount of memory used up by a large query may be gigantic. Use the max_rows parameter to limit the maximum number of rows returned, unless you are absolutely sure that your result will not use up all available memory.

See also: sesam_fetch_row(), and sesam_field_array() to check for "multiple fields". See the description of the sesam_query() function for a complete example using sesam_fetch_result().

sesam_fetch_row

(PHP 3 CVS only)

sesam_fetch_row -- Fetch one row as an array

Description

array sesam_fetch_row ( string result_id [, int whence [, int offset]] )

Returns an array that corresponds to the fetched row, or FALSE if there are no more rows.

The number of columns in the result set is returned in an associative array element $array["count"]. Because some of the result columns may be empty, the count() function can not be used on the result row returned by sesam_fetch_row().

result_id is a valid result id returned by sesam_query() (select type queries only!).

whence is an optional parameter for a fetch operation on "scrollable" cursors, which can be set to the following predefined constants:

Tabella 1. Valid values for "whence" parameter

Value	Constant	Meaning
0	`SESAM_SEEK_NEXT`	read sequentially (after fetch, the internal default is set to `SESAM_SEEK_NEXT`)
1	`SESAM_SEEK_PRIOR`	read sequentially backwards (after fetch, the internal default is set to `SESAM_SEEK_PRIOR`)
2	`SESAM_SEEK_FIRST`	rewind to first row (after fetch, the default is set to `SESAM_SEEK_NEXT`)
3	`SESAM_SEEK_LAST`	seek to last row (after fetch, the default is set to `SESAM_SEEK_PRIOR`)
4	`SESAM_SEEK_ABSOLUTE`	seek to absolute row number given as `offset` (Zero-based. After fetch, the internal default is set to `SESAM_SEEK_ABSOLUTE`, and the internal offset value is auto-incremented)
5	`SESAM_SEEK_RELATIVE`	seek relative to current scroll position, where `offset` can be a positive or negative offset value.

This parameter is only valid for "scrollable" cursors.

When using "scrollable" cursors, the cursor can be freely positioned on the result set. If the whence parameter is omitted, the global default values for the scrolling type (initialized to: SESAM_SEEK_NEXT, and settable by sesam_seek_row()) are used. If whence is supplied, its value replaces the global default.

offset is an optional parameter which is only evaluated (and required) if whence is either SESAM_SEEK_RELATIVE or SESAM_SEEK_ABSOLUTE. This parameter is only valid for "scrollable" cursors.

sesam_fetch_row() fetches one row of data from the result associated with the specified result identifier. The row is returned as an array (indexed by values between 0 and $array["count"]-1). Fields may be empty, so you must check for the existence of a field by using the isset() function. The type of the returned fields depend on the respective SQL type declared for its column (see SESAM overview for the conversions applied). SESAM "multiple fields" are "inlined" and treated like a sequence of columns.

Subsequent calls to sesam_fetch_row() would return the next (or prior, or n'th next/prior, depending on the scroll attributes) row in the result set, or FALSE if there are no more rows.

Esempio 1. SESAM fetch rows

<?php
$result = sesam_query("SELECT * FROM phone\n" .
                       "  WHERE LASTNAME='" . strtoupper($name) . "'\n" .
                       "  ORDER BY FIRSTNAME", 1);
if (!$result) {
    /* ... error ... */
}
// print the table in backward order
echo "<table border=\"1\">\n";
$row = sesam_fetch_row($result, SESAM_SEEK_LAST);
while (is_array($row)) {
    echo "<tr>\n";
    for ($col = 0; $col < $row["count"]; ++$col) {
        echo "<td>" . htmlspecialchars($row[$col]) . "</td>\n";
    }
    echo "</tr>\n";
    // use implied SESAM_SEEK_PRIOR
    $row = sesam_fetch_row($result);
}
echo "</table>\n";
sesam_free_result($result);
?>

See also: sesam_fetch_array() which returns an associative array, and sesam_fetch_result() which returns many rows per invocation.

sesam_field_array

(PHP 3 CVS only)

sesam_field_array -- Return meta information about individual columns in a result

Description

array sesam_field_array ( string result_id )

result_id is a valid result id returned by sesam_query().

Returns a mixed associative/indexed array with meta information (column name, type, precision, ...) about individual columns of the result after the query associated with result_id.

Tabella 1. Mixed result set returned by sesam_field_array()

Array Element	Contents
int $arr["count"]	Total number of columns in result set (or zero if this was an "immediate" query). SESAM "multiple fields" are "inlined" and treated like the respective number of columns.
string $arr[col]["name"]	column name for column(`col`), where `col` is between 0 and `$arr["count"]-1`. The returned value can be the empty string (for dynamically computed columns). SESAM "multiple fields" are "inlined" and treated like the respective number of columns, each with the same column name.
string $arr[col]["count"]	The "count" attribute describes the repetition factor when the column has been declared as a "multiple field". Usually, the "count" attribute is 1. The first column of a "multiple field" column however contains the number of repetitions (the second and following column of the "multiple field" contain a "count" attribute of 1). This can be used to detect "multiple fields" in the result set. See the example shown in the sesam_query() description for a sample use of the "count" attribute.
string $arr[col]["type"]	PHP variable type of the data for column(`col`), where `col` is between 0 and `$arr["count"]-1`. The returned value can be one of integer float string depending on the SQL type of the result. SESAM "multiple fields" are "inlined" and treated like the respective number of columns, each with the same PHP type.
string $arr[col]["sqltype"]	SQL variable type of the column data for column(`col`), where `col` is between 0 and `$arr["count"]-1`. The returned value can be one of "CHARACTER" "VARCHAR" "NUMERIC" "DECIMAL" "INTEGER" "SMALLINT" "FLOAT" "REAL" "DOUBLE" "DATE" "TIME" "TIMESTAMP" describing the SQL type of the result. SESAM "multiple fields" are "inlined" and treated like the respective number of columns, each with the same SQL type.
string $arr[col]["length"]	The SQL "length" attribute of the SQL variable in column(`col`), where `col` is between 0 and `$arr["count"]-1`. The "length" attribute is used with "CHARACTER" and "VARCHAR" SQL types to specify the (maximum) length of the string variable. SESAM "multiple fields" are "inlined" and treated like the respective number of columns, each with the same length attribute.
string $arr[col]["precision"]	The "precision" attribute of the SQL variable in column(`col`), where `col` is between 0 and `$arr["count"]-1`. The "precision" attribute is used with numeric and time data types. SESAM "multiple fields" are "inlined" and treated like the respective number of columns, each with the same precision attribute.
string $arr[col]["scale"]	The "scale" attribute of the SQL variable in column(`col`), where `col` is between 0 and `$arr["count"]-1`. The "scale" attribute is used with numeric data types. SESAM "multiple fields" are "inlined" and treated like the respective number of columns, each with the same scale attribute.

See also sesam_query() for an example of the sesam_field_array() use.

sesam_field_name

(PHP 3 CVS only)

sesam_field_name -- Return one column name of the result set

Description

int sesam_field_name ( string result_id, int index )

Returns the name of a field (i.e., the column name) in the result set, or FALSE on error.

For "immediate" queries, or for dynamic columns, an empty string is returned.

Nota: The column index is zero-based, not one-based as in SESAM.

See also: sesam_field_array(). It provides an easier interface to access the column names and types, and allows for detection of "multiple fields".

sesam_free_result

(PHP 3 CVS only)

sesam_free_result -- Releases resources for the query

Description

int sesam_free_result ( string result_id )

Releases resources for the query associated with result_id. Returns FALSE on error.

sesam_num_fields

(PHP 3 CVS only)

sesam_num_fields -- Return the number of fields/columns in a result set

Description

int sesam_num_fields ( string result_id )

After calling sesam_query() with a "select type" query, this function gives you the number of columns in the result. Returns an integer describing the total number of columns (aka. fields) in the current result_id result set or FALSE on error.

For "immediate" statements, the value zero is returned. The SESAM "multiple field" columns count as their respective dimension, i.e., a three-column "multiple field" counts as three columns.

See also: sesam_query() and sesam_field_array() for a way to distinguish between "multiple field" columns and regular columns.

sesam_query

(PHP 3 CVS only)

sesam_query -- Perform a SESAM SQL query and prepare the result

Description

string sesam_query ( string query [, bool scrollable] )

Returns: A SESAM "result identifier" on success, or FALSE on error.

A "result_id" resource is used by other functions to retrieve the query results.

sesam_query() sends a query to the currently active database on the server. It can execute both "immediate" SQL statements and "select type" queries. If an "immediate" statement is executed, then no cursor is allocated, and any subsequent sesam_fetch_row() or sesam_fetch_result() call will return an empty result (zero columns, indicating end-of-result). For "select type" statements, a result descriptor and a (scrollable or sequential, depending on the optional boolean scrollable parameter) cursor will be allocated. If scrollable is omitted, the cursor will be sequential.

For "immediate" statements, the number of affected rows is saved for retrieval by the sesam_affected_rows() function.

See also: sesam_fetch_row() and sesam_fetch_result().
Esempio 1. Show all rows of the "phone" table as a HTML table
<?php if (!sesam_connect("phonedb", "demo", "otto")) die("cannot connect"); $result = sesam_query("select * from phone"); if (!$result) { $err = sesam_diagnostic(); die ($err["errmsg"]); } echo "<table border>\n"; // Add title header with column names above the result: if ($cols = sesam_field_array($result)) { echo "<tr><th colspan=" . $cols["count"] . ">Result:</th></tr>\n"; echo "<tr>\n"; for ($col = 0; $col < $cols["count"]; ++$col) { $colattr = $cols[$col]; /* Span the table head over SESAM's "Multiple Fields": */ if ($colattr["count"] > 1) { echo "<th colspan=\"" . $colattr["count"] . "\">" . $colattr["name"] . "(1.." . $colattr["count"] . ")</th>\n"; $col += $colattr["count"] - 1; } else echo "<th>" . $colattr["name"] . "</th>\n"; } echo "</tr>\n"; } do { // Fetch the result in chunks of 100 rows max. $ok = sesam_fetch_result($result, 100); for ($row=0; $row < $ok["rows"]; ++$row) { echo " <tr>\n"; for ($col = 0; $col < $ok["cols"]; ++$col) { if (isset($ok[$col][$row])) { echo "<td>" . $ok[$col][$row] . "</td>\n"; } else { echo "<td>-empty-</td>\n"; } } echo "</tr>\n"; } } while ($ok["truncated"]); // while there may be more data echo "</table>\n"; // free result id sesam_free_result($result); ?>

sesam_rollback

(PHP 3 CVS only)

sesam_rollback -- Discard any pending updates to the SESAM database

Description

bool sesam_rollback ( void )

Returns: TRUE on success, FALSE on errors

sesam_rollback() discards any pending updates to the database. Also affected are result cursors and result descriptors.

At the end of each script, and as part of the sesam_disconnect() function, an implied sesam_rollback() is executed, discarding any pending changes to the database.

See also: sesam_commit().
Esempio 1. Discarding an update to the SESAM database
<?php if (sesam_connect ("mycatalog", "myschema", "otto")) { if (sesam_execimm ("INSERT INTO mytable VALUES (*, 'Small Test', <0, 8, 15>)") && sesam_execimm ("INSERT INTO othertable VALUES (*, 'Another Test', 1)")) { sesam_commit(); } else { sesam_rollback(); } } ?>

sesam_seek_row

(PHP 3 CVS only)

sesam_seek_row -- Set scrollable cursor mode for subsequent fetches

Description

bool sesam_seek_row ( string result_id, int whence [, int offset] )

result_id is a valid result id (select type queries only, and only if a "scrollable" cursor was requested when calling sesam_query()).

whence sets the global default value for the scrolling type, it specifies the scroll type to use in subsequent fetch operations on "scrollable" cursors, which can be set to the following predefined constants:

Tabella 1. Valid values for "whence" parameter

Value	Constant	Meaning
0	`SESAM_SEEK_NEXT`	read sequentially
1	`SESAM_SEEK_PRIOR`	read sequentially backwards
2	`SESAM_SEEK_FIRST`	fetch first row (after fetch, the default is set to `SESAM_SEEK_NEXT`)
3	`SESAM_SEEK_LAST`	fetch last row (after fetch, the default is set to `SESAM_SEEK_PRIOR`)
4	`SESAM_SEEK_ABSOLUTE`	fetch absolute row number given as `offset` (Zero-based. After fetch, the default is set to `SESAM_SEEK_ABSOLUTE`, and the offset value is auto-incremented)
5	`SESAM_SEEK_RELATIVE`	fetch relative to current scroll position, where `offset` can be a positive or negative offset value (this also sets the default "offset" value for subsequent fetches).

offset is an optional parameter which is only evaluated (and required) if whence is either SESAM_SEEK_RELATIVE or SESAM_SEEK_ABSOLUTE.

sesam_settransaction

(PHP 3 CVS only)

sesam_settransaction -- Set SESAM transaction parameters

Description

bool sesam_settransaction ( int isolation_level, int read_only )

Returns: TRUE if the values are valid, and the settransaction() operation was successful, FALSE otherwise.

sesam_settransaction() overrides the default values for the "isolation level" and "read-only" transaction parameters (which are set in the SESAM configuration file), in order to optimize subsequent queries and guarantee database consistency. The overridden values are used for the next transaction only.

sesam_settransaction() can only be called before starting a transaction, not after the transaction has been started already.

To simplify the use in PHP scripts, the following constants have been predefined in PHP (see SESAM handbook for detailed explanation of the semantics):

Tabella 1. Valid values for "Isolation_Level" parameter

Value	Constant	Meaning
1	`SESAM_TXISOL_READ_UNCOMMITTED`	Read Uncommitted
2	`SESAM_TXISOL_READ_COMMITTED`	Read Committed
3	`SESAM_TXISOL_REPEATABLE_READ`	Repeatable Read
4	`SESAM_TXISOL_SERIALIZABLE`	Serializable

Tabella 2. Valid values for "Read_Only" parameter

Value	Constant	Meaning
0	`SESAM_TXREAD_READWRITE`	Read/Write
1	`SESAM_TXREAD_READONLY`	Read-Only

The values set by sesam_settransaction() will override the default setting specified in the SESAM configuration file.

Esempio 1. Setting SESAM transaction parameters
<?php sesam_settransaction (SESAM_TXISOL_REPEATABLE_READ, SESAM_TXREAD_READONLY); ?>

CXXXIII. PostgreSQL Session Save Handler

Introduzione

Nota: Questo modulo non è disponibile su piattaforme Windows.

This module provides an additional session save handler for the session module using PostgreSQLPostgreSQL as a storage system. A user session save handler may be used ((session_set_save_handler(), but this module is written in C. Therefore, this module could be twice as fast, compared to a session save handler written in PHP.

Session PgSQL is designed to scale any size of web sites and offers some advanced features:

session tables are created automatically

automatic session table vacuum

better garbage collection

multiple PostgreSQL servers support

automatic database server failover (switching)

automatic database server load balancing if there are multiple PostgreSQL servers.

short circuit UPDATE

Requisiti

You need at least PHP >= 4.3.0, and PostgreSQL >=7.2.0 as database server. libpq that comes with PostgreSQL 7.2.0 or later (and header files to build) and libmm (and header files).

Installazione

Short installation note:

Untar the tar.gz archive into php4/ext (Latest official releases can be found at SourceForge PHP Form Extension Project)
If the new directory is now called something like session_pgsql. You should name it to session_pgsql (except you only want to build it as self-contained php-module).
Run ./buildconf in php4
Run configure --with-session-pgsql (and your other options)
make; make install

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

PostgreSQL session save handler is still under development. Refer to the README file in the source distribution for configuration details.

Table definitions

Session table definition
CREATE TABLE php_session ( sess_id text, sess_name text, sess_data text, sess_created integer, sess_modified integer, sess_expire integer, sess_addr_created text, sess_addr_modified text, sess_counter integer, sess_error integer, sess_warning integer, sess_notice integer, sess_err_message text, sess_custom text ); CREATE INDEX php_session_idx ON php_session USING BTREE (sess_id);

Avvertimento

If you use HASH for INDEX, you'll have a deadlock problem when the server load is very high. Even if it's unlikely to have a deadlock under normal operation, it can occur. Do not use HASH for INDEX.

You may change the session table as long as all fields are defined.

Application variables table definition
CREATE TABLE php_app_vars ( app_modified integer, app_name text, app_vars text );

Contact Information

I have at the moment not very much time to further develop this extension. I will implement more and more features in the near future.

If you have comments, bug fixes, enhancements or want to help developing this, you can drop me a mail at yohgaki@php.net. Any help is very welcome.

Sommario
session_pgsql_add_error -- Increments error counts and sets last error message
session_pgsql_get_error -- Returns number of errors and last error message
session_pgsql_get_field -- Get custom field value
session_pgsql_reset -- Reset connection to session database servers
session_pgsql_set_field -- Set custom field value
session_pgsql_status -- Get current save handler status

session_pgsql_add_error

(PECL)

session_pgsql_add_error -- Increments error counts and sets last error message

Descrizione

bool session_pgsql_add_error ( int error_level [, string error_message] )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Elenco dei parametri

error_level
error_message

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

session_pgsql_get_error()

session_pgsql_get_error

(PECL)

session_pgsql_get_error -- Returns number of errors and last error message

Descrizione

array session_pgsql_get_error ( [bool with_error_message] )

Get the number of errors and optional the error messages.

Elenco dei parametri

with_error_message: Set to TRUE the literal error message for each error is also returned.

Valori restituiti

The number of errors are returned as array.

Vedere anche:

session_pgsql_add_error()

session_pgsql_get_field

(PECL)

session_pgsql_get_field -- Get custom field value

Descrizione

string session_pgsql_get_field ( void )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Vedere anche:

session_pgsql_set_field()

session_pgsql_reset

(PECL)

session_pgsql_reset -- Reset connection to session database servers

Descrizione

bool session_pgsql_reset ( void )

Reset the connection to the session database servers.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

session_pgsql_set_field

(PECL)

session_pgsql_set_field -- Set custom field value

Descrizione

bool session_pgsql_set_field ( string value )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Elenco dei parametri

value

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

session_pgsql_get_field()

session_pgsql_status

(PECL)

session_pgsql_status -- Get current save handler status

Descrizione

array session_pgsql_status ( void )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

CXXXIV. Funzioni di gestione della sessione

Il supporto delle sessioni in PHP consiste nel mantenere certi dati attraverso accessi successivi.Questo vi dà la capacità di costruire applicazioni più consone alle vostre esigenze e di accrescere le qualità del vostro sito web.

Se avete dimestichezza con la gestione delle sessioni di PHPLIB, noterete che alcuni concetti sono simili al supporto dele sessioni in PHP.

Al visitatore che accede al vostro sito web viene assegnato un id unico, il cosidetto id di sessione. Questo viene registrato in un cookie sul lato utente o è propagato tramite l'URL.

Il supporto delle sessioni vi permette di registrare numeri arbitrari di variabili che vengono preservate secondo richiesta.Quando un visitatore accede al vostro sito, PHP controllerà automaticamente (se session.auto_start è settato a 1) o su vostra richiesta (esplicitamente tramite session_start() o implicitamente tramite session_register()) se uno specifico id di sessione sia stato inviato con la richiesta. In questo caso , il precedente ambiente salvato viene ricreato.

Tutte le variabili registrate vengono serializzate dopo che la richiesta è finita. Le variabili registrate che non sono definite vengono marcate come indefinite. All'accesso successivo, queste non vengono definite dal modulo di sessione fino a quando l'utente non le definisce più tardi.

La configurazione di track_vars e register_globals influenza come le variabili di sessione vengono memorizzate una e più volte.

Nota: In PHP 4.0.3, track_vars è sempre attiva.

Nota: In PHP 4.1.0, $_SESSION è disponibile come variabile globale proprio come $_POST, $_GET, $_REQUEST e così via. $HTTP_SESSION_VARS non è sempre globale, $_SESSION lo è sempre. Per questo motivo, global non dovrebbe essere usato per $_SESSION.

Se track_vars è attiva e register_globals non è attiva, solo i membri dell'array associativo globale $HTTP_SESSION_VARS possono essere registrati come variabili di sessione. Le variabili di sessione ripristinate saranno disponibili nell'array $HTTP_SESSION_VARS.
Esempio 1. Registrare una variabile con track_vars attiva
<?php if (isset($HTTP_SESSION_VARS['count'])) { $HTTP_SESSION_VARS['count']++; } else { $HTTP_SESSION_VARS['count'] = 0; } ?>

L'uso di $_SESSION (o $HTTP_SESSION_VARS con PHP 4.0.6 o precedente) è raccomandato per sicurezza e leegibilità del codice.Con $_SESSION o $HTTP_SESSION_VARS, non c'è bisogno di usare le funzioni session_register()/session_unregister()/session_is_registered(). Gli utenti possono accedere alla variabile di sessione come a una variabile normale.
Esempio 2. Registrare una variabile con $_SESSION.
<?php // Use $HTTP_SESSION_VARS with PHP 4.0.6 or less if (!isset($_SESSION['count'])) { $_SESSION['count'] = 0; } else { $_SESSION['count']++; } ?>

Esempio 3. Resettare una variabile con $_SESSION.
<?php // Use $HTTP_SESSION_VARS with PHP 4.0.6 or less unset($_SESSION['count']); ?>

Se register_globals è attiva, allora tutte le variabili globali possono essere registrate come variabili di sessione e le variabili di sessione saranno ripristinate in corrispondenza delle variabili globali. Dal momento che PHP ha bisogno di sapere quali variabili globali sono registrate come variabili di sessione , gli utenti devono registrare le variabili con la funzione session_register() mentre $HTTP_SESSION_VARS/$_SESSION non ha bisogno di usare session_register().

Attenzione

Se state usando $HTTP_SESSION_VARS/$_SESSION e register_globals non è attiva, non usate session_register(), session_is_registered() e session_unregister().

Se attivate register_globals, session_unregister() dovrebbe essere usata dal momento in cui le variabili di sessione vengono registrate come variabili globali quando i dati di sessione vengono deserializzati. Disattivare register_globals è raccomandato sia per motivi di sicurezza che di prestazione.

Esempio 4. Registrare una variabile con register_globals attiva

<?php
if (!session_is_registered('count')) {
    session_register("count");
    $count = 0;
}
else {
    $count++;
}
?>

Se entrambe track_vars e register_globals sono attivate, allora le variabili globali e le entrate di $HTTP_SESSION_VARS/$_SESSION riporteranno lo stesso valore per variabili già registrate.

Se l'utente usa session_register() pre registrare una variabile di sessione, $HTTP_SESSION_VARS/$_SESSION non avranno questa variabile nell'array fino a che non sarà caricata dall'archivio di sessione.(i.e. fino alla prossima richiesta)

Ci sono due metodi per propagare l'id di sessione:

I Cookies
Un parametro dell'URL

Il modulo di sessione supporta entrambi i metodi. I cookies sono ottimi, ma dal momento che possono non essere a disposizione (i clients non sono costretti ad accettarli ), non possiamo dipendere da questi. Il secondo metodo incorpora l'id di sessione direttamente negli URL.

PHP ha la capacità di farlo in modo trasparente quando compilato con --enable-trans-sid. Se attivate questa opzione, gli URL relativi saranno modificati per contenere l'id di sessione automaticamente. In alternativa, potete usare la costante Alternatively, you can use the constant SID che è definita, se il client non ha mandato il cookie appropriato. SID può avere la forma di session_name=session_id o può essere una stringa vuota.

L'esempio seguente dimostra come registrare una variabile e come collegare una pagina all'altra correttamente usando SID.
Esempio 5. Contare il numero di accessi di un singolo utente
<?php if (!session_is_registered('count')) { session_register('count'); $count = 1; } else { $count++; } ?> Salve visitatore , hai visitato questa pagina <?php echo $count; ?> times.<p>; <?php # il <?php echo SID?> (<?=SID?> può essere usato se short tag è attivo) # è necessario per preservare l'id di sessione # nel caso incui l'utente abbia disattivato i cookies ?> Per continuare, <A HREF="nextpage.php?<?php echo SID?>">clicca qui</A>

Il <?=SID?> non è necessario, se --enable-trans-sid è stato usato per compilare PHP.

Nota: Gli URL non relativi si presume che puntino a siti esterni e quindi non hanno il SID , perchè sarebbe rischioso per la sicurezza propagare il SID a un altro server.

Per implementare l'archiviazione in database , o qualsiasi altro metodo di archiviazione, avete bisogno di usare session_set_save_handler() per creare un set di funzioni di archiviazione a livello utente.

Il sistema di gestione delle sessioni supporta un numero di opzioni di configurazione che potete posizionare nel vostro file php.ini. Ne daremo una breve spiegazione.

session.save_handler definisce il nome dell'handler che è usato per archiviare e rilasciare i dati associati a una sessione. Di default è files.

session.save_path definisce l'argomento che è passato all'handler di sessione. Se scegliete handler files di default , questo è il percorso dove i files vengono creati. Di default è /tmp. Se la profondità del percorso session.save_path è più di 2, l'accumulo (gc) non sarà effettuato.

Avvertimento

Se lasciate questo settato a directory leggibile da tutti , come If you leave this set to a world-readable directory, such as /tmp (il default), altri utenti sul potrebbero essere in grado di dirottare le sessioni prendendo la lista dei files in quella directory.

session.name specifica il nome della sessione che è usata come nome del cookie. Dovrebbe contenere solo caratteri alfanumerici. Di default è PHPSESSID.
session.auto_start specifica se il modulo di sessione inizia una sessione automaticamente su richiesta iniziale. Di default è 0 (disattivata).
session.cookie_lifetime specifica il tempo di vita insecondi del cookie che viene mandato al browser. Il valore 0 significa "fino a che il browser viene chiuso". Di default è 0.
session.serialize_handler definisce il nome dell'handler che è usato per serializzare/deserializzare i dati. Al momento, un formato interno di PHP(nome php) e WDDX è supportato (nome wddx). WDDX è solo disponibile, se PHP è compilato con WDDX support. Il defailt è php.
session.gc_probability specifica la probabilità , in percentuale ,che la routine gc (garbage collection) sia cominciata ad ogni richiesta in percentuale. Di default è 1.
session.gc_maxlifetime specifica il numero di secondi dopo i quali i dati saranno considerati 'spazzatura' e cancellati.
session.referer_check contiene la sottostringa con cui volete controllare ogni HTTP referer. Se il referer è stato mandato dal client e la sottostringa non è stata trovata, l'id incorporato nella sessione verrà marcato come non valido. Il default è una stringa vuota.
session.entropy_file dà un percorso a una risorsa esterna (file) che sarà usata come una addizionale sorgente entropica nella crazione dell'id di sessione. Esempi sono /dev/random o /dev/urandom che sono disponibili sulla maggior parte dei sistemi Unix.
session.entropy_length specifica il numero di bytes che saranno letti dal file specificato sopra. Di default è 0 (disattivato).
session.use_cookies specifica se il modulo userà i cookies per archiviare l'id di sessione sul lato client. Di default è 1 (attivo).
session.cookie_path specifica il percorso da stabilire in session_cookie. Di default è /.
session.cookie_domain specifica il dominio settato in session_cookie. Di default è niente.
session.cache_limiter specifica il metodo di controllo della cache da usare per le pagine di sessione (none/nocache/private/private_no_expire/public). Di default è nocache.
session.cache_expire specifica il tempo-di-vita , in minuti , delle pagine nella cache, questo non ha effetto sul limitatore nocache. Di default è 180.
session.use_trans_sid specifica se il supporto sid trasparente è attivato o no se attivato compilandolo con --enable-trans-sid. Di default è 1 (attivo).
url_rewriter.tags specifica quali html tags sono riscritti per includere l'id di sessione se il supporto sid trasparente è attivato. Di default è a=href,area=href,frame=src,input=src,form=fakeentry

Nota: L'handling di sessione è stato aggiunto in PHP 4.0.

Sommario
session_cache_expire -- Ritorna il valore corrente di scadenza della cache
session_cache_limiter -- Assume o imposta il limitatore di cache corrente
session_commit -- Alias di session_write_close()
session_decode -- Decodifica i dati di sessione da una stringa
session_destroy -- Distrugge tutti i dati registrati in una sessione
session_encode -- Codifica i dati della sessione corrente in una stringa
session_get_cookie_params -- Restituisce i parametri del cookie di sessione
session_id -- Assume o imposta l'id di sessione corrente
session_is_registered -- Scopre se una variabile è registrata nella sessione
session_module_name -- Assume o imposta il corrente modulo di sessione
session_name -- Dà e/o stabilisce il nome della sessione corrente
session_regenerate_id -- Update the current session id with a newly generated one
session_register -- Registra una o più variabili con la sessione corrente
session_save_path -- Assume o stabilisce il percorso di salvataggio sessione corrente
session_set_cookie_params -- Imposta i parametri del cookie di sessione
session_set_save_handler -- Imposta le funzioni di archiviazione sessioni a livello utente
session_start -- Inizializza i dati di sessione
session_unregister -- Deregistra una variabile dalla sessione corrente
session_unset -- Libera tutte le variabili di sessione
session_write_close -- Scrive i dati di sessione e termina la sessione

session_cache_expire

(PHP 4 >= 4.2.0, PHP 5)

session_cache_expire -- Ritorna il valore corrente di scadenza della cache

Descrizione

int session_cache_expire ( [int nuova_scadenza_cache] )

session_cache_expire() ritorna il valore corrente di session.cache_expire. Il valore ritornato deve essere espressio in minuti, di default 180. Se si assegna nuova_scadenza_cache , il valore corrente di scadenza della cache viene sostituito con nuova_scadenza_cache.

La scadenza della cache viene reimpostata al valore predefinito di 180 memorizzato in session.cache_limiter ad ogni richiesta di pagina. Quindi, è necessario chiamare session_cache_expire() in ogni pagina (e prima di invocare session_start()).

Esempio 1. session_cache_expire() esempio

<?php

/* assegna il limite della cache su 'private' */

session_cache_limiter('private');
$cache_limiter = session_cache_limiter();

/* imposta la scadenza della cache su 30 minuti */
session_cache_expire(30);
$cache_expire = session_cache_expire();

/* avvia la sessione */

session_start();

echo "Il limite della cache ora è impostato su $cache_limiter<br />";
echo "Le pagine di sessione nella cache scadranno dopo $cache_expire minutes";
?>

Nota: Impostazione nuova_scadenza_cache è utile soltanto, se session.cache_limiter è impostato su un valore diverso da nocache.

Vedere inoltre le impostazioni di configurazione session.cache_expire, session.cache_limiter e session_cache_limiter().

session_cache_limiter

(PHP 4 >= 4.0.3, PHP 5)

session_cache_limiter -- Assume o imposta il limitatore di cache corrente

Descrizione

string session_cache_limiter ( [string cache_limiter] )

session_cache_limiter() restituisce il nome del limitatore di cache corrente. Se cache_limiter è specificato, il nome del limitatore di cache corrente viene cambiato nel nuovo valore.

Il limitatore di cache controlla quali header HTTP che influenzano la cache vengono mandati al client. Questi header determinano i modi in cui il contenuto della pagina può essere mandato in cache, sia da parte del client che da parte di eventuali proxy. Impostando il limitatore di cache a nocache, per esempio, non permetterebbe nessun caching lato client. Un valore di public, invece, permetterebbe il caching. Può anche essere impostato a private, che è leggermente più restrittivo di public.

Nella modalità private, l'header Expire mandato al client, potrebbe causare confusione per alcuni browser incluso Mozilla. Si può evitare questo problema con la modalità private_no_expire. In questo modo l'header Expire non viene mai spedito al client.

Nota: private_no_expire è stato aggiunto in PHP 4.2.0dev.

Il limitatore di cache è resettato al valore di default archiviato in session.cache_limiter alla richiesta iniziale. Per questo motivo, avete bisogno di chiamare session_cache_limiter() per ogni richiesta (e prima che session_start() sia chiamata).

Esempio 1. session_cache_limiter() esempi

<?php

# set the cache limiter to 'private'

session_cache_limiter('private');
$cache_limiter = session_cache_limiter();

echo "Il limitatore di cache è adesso impostato a $cache_limiter<p>";
?>

session_commit

(PHP 4 >= 4.3.11, PHP 5)

session_commit -- Alias di session_write_close()

Descrizione

This function is an alias of: session_write_close().

session_decode

(PHP 4, PHP 5)

session_decode -- Decodifica i dati di sessione da una stringa

Descrizione

bool session_decode ( string data )

session_decode() decodifica i dati di sessione in data, impostando le varibili archiviate nella sessione.

Vedere inoltre session_encode().

session_destroy

(PHP 4, PHP 5)

session_destroy -- Distrugge tutti i dati registrati in una sessione

Descrizione

bool session_destroy ( void )

session_destroy() distrugge tutti i dati associati alla sessione corrente. Non desetta nessuna delle variabili globali associate alla sessione o desetta il cookie di sessione.

Questa funzione ritorna TRUE in caso di successo e FALSE in caso di fallimento nel distruggere i dati di sessione.

Esempio 1. Distruggere una sessione
<?php // Inizializza la sessione. // Se state usando session_name("qualcosa"), non dimenticatevelo adesso! session_start(); // Desetta tutte le variabili di sessione. session_unset(); // Infine , distrugge la sessione. session_destroy(); ?>

Esempio 2. Distruggere una sessione con $_SESSION
<?php // Inizializza la sessione. // Se state usando session_name("qualcosa"), non dimenticatevelo adesso! session_start(); // Desetta tutte le variabili di sessione. $_SESSION = array(); // Infine distrugge la sessione. session_destroy(); ?>

session_encode

(PHP 4, PHP 5)

session_encode -- Codifica i dati della sessione corrente in una stringa

Descrizione

session_is_registered() restituisce TRUE se c'è una variabile con il nome name registrato nella sessione corrente.

Nota: Se è usata $_SESSION (o $HTTP_SESSION_VARS per PHP 4.0.6 o inferiore), usate isset() per controllare che una variabile sia registrata in $_SESSION.

Attenzione

Se state usando $HTTP_SESSION_VARS/$_SESSION, non usate session_register(), session_is_registered() e session_unregister().

session_module_name

(PHP 4, PHP 5)

session_module_name -- Assume o imposta il corrente modulo di sessione

Descrizione

string session_module_name ( [string module] )

session_module_name() restituisce il nome del corrente modulo di sessione. Se module è specificato, sarà invece usato quel modulo.

session_name

(PHP 4, PHP 5)

session_name -- Dà e/o stabilisce il nome della sessione corrente

Descrizione

string session_name ( [string name] )

session_name() ritorna il nome della sessione corrente. Se name è specificato, il nome della sessione corrente viene cambiato al suo valore.

Il nome della sessione riporta l'id nei coookies e negli URl. Dovrebbe contenere solo caratteri alfanumerici; dovrebbe essere corto e descrittivo (i.e. per utenti con l'avviso di cookie attivo). Il nome di sessione è resettato al valore di default archiviato in session.name quando avviene la richiesta iniziale. Tuttavia, avete bisogno di chiamare session_name() per ogni richiesta (e prima vengono chiamate session_start() o session_register()).

Esempio 1. session_name() esempi

<?php

// imposta il nome di sessione a WebsiteID

$previous_name = session_name("WebsiteID");

echo "Il precedente nome di sessione è $previous_name<p>";
?>

session_regenerate_id

(PHP 4 >= 4.3.2, PHP 5)

session_regenerate_id -- Update the current session id with a newly generated one

Descrizione

bool session_regenerate_id ( [bool delete_old_session] )

session_regenerate_id() will replace the current session id with a new one, and keep the current session information.

Elenco dei parametri

delete_old_session: Whether to delete the old associated session file or not. Defaults to FALSE.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Log delle modifiche

Versione	Descrizione
4.3.3	Since then, if session cookies are enabled, use of session_regenerate_id() will also submit a new session cookie with the new session id.
5.1.0	Added the `delete_old_session` parameter.

Esempi

Esempio 1. A session_regenerate_id() example
<?php session_start(); $old_sessionid = session_id(); session_regenerate_id(); $new_sessionid = session_id(); echo "Old Session: $old_sessionid<br />"; echo "New Session: $new_sessionid<br />"; print_r($_SESSION); ?>

Vedere anche:

session_id()

session_start()

session_name()

session_register

(PHP 4, PHP 5)

session_register -- Registra una o più variabili con la sessione corrente

Descrizione

bool session_register ( mixed name [, mixed ...] )

session_register() accetta un numero di argomenti variabile, ognuno dei quali può sia essere una stringa contenente il nome di una variabile o un array che contiene i nomi delle variabili o altri arrays. Per ogni nome, session_register() registra la variabile globale con quel nome nella sessione corrente.

Attenzione

Questo registra un variabile global. Se volete registrare una variabile di sessione interna a una funzione, avete bisogno di assicurarvi di farla globale usando global() o usate gli arrays di sessione come scritto sotto.

Attenzione

Se state usando $HTTP_SESSION_VARS/$_SESSION, non usate session_register(), session_is_registered() e session_unregister().

Questa funzione restituisce TRUE quando tutte le variabili sono registrate con successo nella sessione.

Se session_start() non è stata chiamata prima che questa funzione venga chiamata, avverrà una chiamata imlicita senza parametri a session_start().

Potete anche creare una variabile di sessione semplicemente impostando l'appropriato membro di $HTTP_SESSION_VARS o $_SESSION (PHP >= 4.1.0) array.

$barney = "Una grande torta fiammeggiante.";
session_register("barney");

$HTTP_SESSION_VARS["zim"] = "Mars attack.";

# the auto-global $_SESSION array was introduced in PHP 4.1.0
$_SESSION["spongebob"] = "Ha i pantaloni a quadri.";

Nota: Non è possibile registrare risorse variabili in una sessione. Per esempio, non potete creare una connessione a un database e archiviare l'id della connessione come una variabile di sessione e aspettarvi che la connessione sia ancora valida la prossima volta che la sessione viene riastabilita. Le funzioni PHP che restituiscono una risorsa sono identificate avendo un tipo di restituzione resource nelle loro definizioni di funzione. Una lista di funzioni che restituisce risorse è disponibile nell'appendice resource types.
Se viene usata $_SESSION (o $HTTP_SESSION_VARS per PHP 4.0.6 or inferiore), assegna la variabile a $_SESSION. i.e. $_SESSION['var'] = 'ABC';

Vedere anche session_is_registered() e session_unregister().

session_save_path

(PHP 4, PHP 5)

session_save_path -- Assume o stabilisce il percorso di salvataggio sessione corrente

Descrizione

string session_save_path ( [string path] )

session_save_path() restituisce il percorso della directory corrente usata per salvare i dati di sessione. Se path è specificato, il percorso in quale i dati vengono salvati verrà cambiata.

Nota: Su alcuni sistemi operativi, potreste voler specificare un percorso su un filesystem che gestisce molti piccoli files in modo efficiente. Per esempio, su Linux, reiserfs potrebbe garantire una migliore prestazione di ext2fs.

session_set_cookie_params

(PHP 4, PHP 5)

session_set_cookie_params -- Imposta i parametri del cookie di sessione

Descrizione

void session_set_cookie_params ( int lifetime [, string path [, string domain]] )

Imposta i parametri del cookie definiti nel file php.ini. L'effetto di questa funzione dura solo per la durata dello script.

session_set_save_handler

(PHP 4, PHP 5)

session_set_save_handler -- Imposta le funzioni di archiviazione sessioni a livello utente

Descrizione

void session_set_save_handler ( string open, string close, string read, string write, string destroy, string gc )

session_set_save_handler() imposta le funzioni di archiviazione sessioni che sono usate per archiviare e riutilizzare i dati associati a una sessione. Ciò non è molto utile quando un altro metodo di archiviazione è preferito a quelli forniti dalle sessioni PHP. i.e. L'archiviazione dei dati di sessione in un database locale.

Nota: Dovete impostare l'opzione di configurazione session.save_handler per user nel vostro file php.ini perchè session_set_save_handler() abbia effetto.

Nota: L'handler "write" non viene eseguito fino a che l'output stream non viene chiuso. In questo modo, l'output di espressioni di debugging nell'hanlder "write" non si vedrà mai nel browser. Se l'output di debugging è necessario, è consigliabile che l'output del debug venga scritto in un file.

Il seguente esempio fornisce l'archiviazione di sessione basata su file simile al solito gestore di salvataggio di sessioni PHP files. Questo esempio potrebbe essere facilmente esteso per coprire l'archiviazione in database usando il vostro sistema database favorito con supporto PHP.

La funzione di lettura deve restituire sempre un valore stringa perchè il save handler funzioni a dovere. Restituisce una stringa vuota se non ci sono dati da leggere. I valori restituiti da altri handlers sono convertiti in espressioni booleane. TRUE per successo, FALSE in caso di fallimento.

Esempio 1. session_set_save_handler() esempio
<?php function open ($save_path, $session_name) { global $sess_save_path, $sess_session_name; $sess_save_path = $save_path; $sess_session_name = $session_name; return(true); } function close() { return(true); } function read ($id) { global $sess_save_path, $sess_session_name; $sess_file = "$sess_save_path/sess_$id"; if ($fp = @fopen($sess_file, "r")) { $sess_data = fread($fp, filesize($sess_file)); return($sess_data); } else { return(""); // Deve restituire "" qui. } } function write ($id, $sess_data) { global $sess_save_path, $sess_session_name; $sess_file = "$sess_save_path/sess_$id"; if ($fp = @fopen($sess_file, "w")) { return(fwrite($fp, $sess_data)); } else { return(false); } } function destroy ($id) { global $sess_save_path, $sess_session_name; $sess_file = "$sess_save_path/sess_$id"; return(@unlink($sess_file)); } /********************************************* * ATTENZIONE - Qui avete bisogno di implementare qualche * * sorta di routine per il cestinaggio. * *********************************************/ function gc ($maxlifetime) { return true; } session_set_save_handler ("open", "close", "read", "write", "destroy", "gc"); session_start(); // proceed to use sessions normally ?>

session_start

(PHP 4, PHP 5)

session_start -- Inizializza i dati di sessione

Descrizione

bool session_start ( void )

session_start() creauna sessione (o riprende quella corrente basata sull'id di sessione che viene passato attraverso una variabile GET o un cookie.

Se volete usare usare una sessione con un nome, dovete chiamare session_name() prima di session_start().

Questa funzione ritorna sempre TRUE.

Nota: Se state usando una sessione basata sui cookie, dovete chiamare session_start() prima di qualsiasi altro output al browser.

session_start() registrerà un handler interno di output per riscrivere l'URL quando trans-sid è attivato. Se l'utente usa ob_gzhandler o come con ob_start(), l'ordine dell'handler di output è importante per un giusto output. Per esempio, l'utente deve registrare ob_gzhandler prima che la sessione cominci.

Nota: L'uso di zlib.output_compression è raccomandato più che di ob_gzhandler

session_unregister

(PHP 4, PHP 5)

session_unregister -- Deregistra una variabile dalla sessione corrente

Descrizione

bool session_unregister ( string name )

session_unregister() deregistra (dimentica) la variabile globale con nome name dalla sessione corrente.

Questa funzione restituisce TRUE quando la variabile viene deregistrata con successo dalla sessione.

Nota: Se viene usata $_SESSION (o $HTTP_SESSION_VARS per PHP 4.0.6 o inferiore), usate unset() per deregistrare una variabile di sessione.

Attenzione

Questa funzione non deimposta la corrispondente variabile globale per name, impedisce solo che la variabile venga salvata come parte della sessione. Dovete chiamare unset() per rimuovere la variabile globale corrispondente.

Attenzione

Se state usando $HTTP_SESSION_VARS/$_SESSION, non usate session_register(), session_is_registered() e session_unregister().

session_unset

(PHP 4, PHP 5)

session_unset -- Libera tutte le variabili di sessione

Descrizione

void session_unset ( void )

La funzione session_unset() libera tutte le variabili di sessione correntemente registrate.

Nota: Se è usata $_SESSION (o $HTTP_SESSION_VARS per PHP 4.0.6 o inferiore) è, usate unset() per deregistrare una variabile di sessione. i.e. $_SESSION = array();

session_write_close

(PHP 4 >= 4.0.4, PHP 5)

session_write_close -- Scrive i dati di sessione e termina la sessione

Descrizione

void session_write_close ( void )

Termina la sessione corrente e archivia i dati di sessione.

I dati di sessione sono di solito archiviati dopo che il vostro script è terminato senza il bisogno di chiamare session_write_close(), ma poichè i dati di sessione vengono bloccati per prevenire scritture contemporanee solo uno script può operare su una sessione in qualsiasi momento. Quando utilizzerete i framesets assieme alla sessione vedrete che i frames vengono caricati uno per uno a causa di questo bloccaggio. Potete ridurre il tempo necessario per caricare tutti i frames terminando la sessione appena tutti i cambi alle variabili di sessione sono stati fatti.

CXXXV. Funzioni relative alla memoria condivisa

Introduzione

Shmop è un set di funzioni di semplice utilizzo che permettono al PHP di leggere, scrivere, creare e cancellare i segmenti di memoria condivisa di Unix.

Nota: Occorre rilevare che nelle versioni di Windows precedenti a Windows 2000 non supportano la memoria condivisa. In Windows, le funzioni Shmop sono eseguilbili solo se il PHP sta girando come server web, tipo con Apache o ISS (nelle modalità CLI o CGI non è utilizzabile). Nella versione 4.0.3 di PHP queste funzioni hanno il prefisso shm anzichè shmop.

Requisiti

Non sono necessarie librerie esterne per utilizzare questo modulo.

Installazione

Per utilizzare shmop occorre compilare il PHP con il parametro --enable-shmop nella linea di configurazione.

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Tipi di risorse

Costanti predefinite

Questa estensione non definisce alcuna costante.

Esempi

Esempio 1. Descrizione delle operazioni con la memoria condivisa
<?php // Crea un blocco di memoria condivisa di 100 byte con id 0xff3 $shm_id = shmop_open(0xff3, "c", 0644, 100); if (!$shm_id) { echo "Non si riesce a creare il segmento di memoria condivisa\n"; } // Ottiene la dimensione del blocco di memoria $shm_size = shmop_size($shm_id); echo "Dimesione blocco creato: " . $shm_size . ".\n"; // Scrittura di una stringa di test nella memoria condivisa $shm_bytes_written = shmop_write($shm_id, "my shared memory block", 0); if ($shm_bytes_written != strlen("my shared memory block")) { echo "Non si riesce a scrivere tutti i dati\n"; } // Ora si rilegge la stringa $my_string = shmop_read($shm_id, 0, $shm_size); if (!$my_string) { echo "Non si riesce a leggere dalla memoria condivisa\n"; } echo "I dati presenti nella memoria condivisa sono: ".$my_string."\n"; // Ora si cancella il blocco e si chiude il segmento di memoria condivisa if (!shmop_delete($shm_id)) { echo "Non si riesce a marcare il blocco di memoria condivisa per la cancellazione."; } shmop_close($shm_id); ?>

Sommario
shmop_close -- Chiusura di un blocco di memoria condivisa
shmop_delete -- Cancella un blocco di memoria condivisa
shmop_open -- Crea oppure apre un segmento di memoria condivisa
shmop_read -- Legge i dati da un segmento di memoria condivisa
shmop_size -- Restituisce la dimensione di un blocco di memoria condivisa
shmop_write -- Scrittura di dati nel blocco di memoria condivisa

Nota: Il terzo ed il quarto parametro dovrebbero essere a 0 se si sta aprendo un segmento di memoria esistene. Se la funzione shmop_open() ha successo, sarà restituito un id da usarsi per accedere al segmento di memoria condivisa appena creato.

Esempio 1. Scrittura di un blocco di memoria condivisa
<?php $shm_bytes_written = shmop_write($shm_id, $my_string, 0); ?>

Questo esempio scrive i dati della variabile $my_string nel blocco di memoria condivisa, mentre $shm_bytes_written contiene il numero dei byte scritti.

CXXXVI. SimpleXML functions

Introduzione

The SimpleXML extension provides a very simple and easily usable toolset to convert XML to an object that can be processed with normal property selectors and array iterators.

Requisiti

The SimpleXML extension requires PHP 5.

Installazione

The SimpleXML extension is enabled by default. To disable it, use the --disable-simplexml configure option.

Esempi

Many examples in this reference require an XML string. Instead of repeating this string in every example, we put it into a file which we include in each example. This included file is shown in the following example section. Alternatively, you could create an XML document and read it with simplexml_load_file().

Esempio 1. Include file example.php with XML string
<?php $xmlstr = <<<XML <?xml version='1.0' standalone='yes'?> <movies> <movie> <title>PHP: Behind the Parser</title> <characters> <character> <name>Ms. Coder</name> <actor>Onlivia Actora</actor> </character> <character> <name>Mr. Coder</name> <actor>El ActÓr</actor> </character> </characters> <plot> So, this language. It's like, a programming language. Or is it a scripting language? All is revealed in this thrilling horror spoof of a documentary. </plot> <rating type="thumbs">7</rating> <rating type="stars">5</rating> </movie> </movies> XML; ?>

The simplicity of SimpleXML appears most clearly when one extracts a string or number from a basic XML document.
Esempio 2. Getting <plot>
<?php include 'example.php'; $xml = simplexml_load_string($xmlstr); echo $xml->movie[0]->plot; // "So this language. It's like..." ?>

Esempio 3. Accessing non-unique elements in SimpleXML
When multiple instances of an element exist as children of a single parent element, normal iteration techniques apply.
<?php include 'example.php'; $xml = simplexml_load_string($xmlstr); /* For each <movie> node, we echo a separate <plot>. */ foreach ($xml->movie as $movie) { echo $movie->plot, '<br />'; } ?>

Esempio 4. Using attributes
So far, we have only covered the work of reading element names and their values. SimpleXML can also access element attributes. Access attributes of an element just as you would elements of an array.
<?php include 'example.php'; $xml = simplexml_load_string($xmlstr); /* Access the <rating> nodes of the first movie. * Output the rating scale, too. */ foreach ($xml->movie[0]->rating as $rating) { switch((string) $rating['type']) { // Get attributes as element indices case 'thumbs': echo $rating, ' thumbs up'; break; case 'stars': echo $rating, ' stars'; break; } } ?>

Esempio 5. Comparing Elements and Attributes with Text
To compare an element or attribute with a string or pass it into a function that requires a string, you must cast it to a string using (string). Otherwise, PHP treats the element as an object.
<?php include 'example.php'; $xml = simplexml_load_string($xmlstr); if ((string) $xml->movie->title == 'PHP: Behind the Parser') { print 'My favorite movie.'; } htmlentities((string) $xml->movie->title); ?>

Esempio 6. Using Xpath
SimpleXML includes builtin Xpath support. To find all <character> elements:
<?php include 'example.php'; $xml = simplexml_load_string($xmlstr); foreach ($xml->xpath('//character') as $character) { echo $character->name, 'played by ', $character->actor, '<br />'; } ?>
'//' serves as a wildcard. To specify absolute paths, omit one of the slashes.

Esempio 7. Setting values
Data in SimpleXML doesn't have to be constant. The object allows for manipulation of all of its elements.
<?php include 'example.php'; $xml = simplexml_load_string($xmlstr); $xml->movie[0]->characters->character[0]->name = 'Miss Coder'; echo $xml->asXML(); ?>
The above code will output a new XML document, just like the original, except that the new XML will change Ms. Coder to Miss Coder.

Esempio 8. DOM Interoperability
PHP has a mechanism to convert XML nodes between SimpleXML and DOM formats. This example shows how one might change a DOM element to SimpleXML.
<?php $dom = new domDocument; $dom->loadXML('<books><book><title>blah</title></book></books>'); if (!$dom) { echo 'Error while parsing the document'; exit; } $s = simplexml_import_dom($dom); echo $s->book[0]->title; ?>

Sommario
SimpleXMLElement->asXML -- Return a well-formed XML string based on SimpleXML element
SimpleXMLElement->attributes -- Identifies an element's attributes
SimpleXMLElement->children -- Finds children of given node
SimpleXMLElement->xpath -- Runs Xpath query on XML data
simplexml_import_dom -- Get a SimpleXMLElement object from a DOM node.
simplexml_load_file -- Interprets an XML file into an object
simplexml_load_string -- Interprets a string of XML into an object

SimpleXMLElement->asXML

(no version information, might be only in CVS)

SimpleXMLElement->asXML -- Return a well-formed XML string based on SimpleXML element

Descrizione

mixed SimpleXMLElement->asXML ( [string filename] )

The asXML method formats the parent object's data in XML version 1.0.

Elenco dei parametri

filename: If specified, the function writes the data to the file rather than returning it.

Valori restituiti

If the filename isn't specified, this function returns a string on success and FALSE on error. If the parameter is specified, it returns TRUE if the file was written successfully and FALSE otherwise.

Esempi

Esempio 1. Get XML
<?php $string = <<<XML <a> <b> <c>text</c> <c>stuff</c> </b> <d> <c>code</c> </d> </a> XML; $xml = simplexml_load_string($string); echo $xml->asXML(); // <?xml ... <a><b><c>text</c><c>stuff</c> ... ?>

asXML also works on Xpath results:
Esempio 2. Using asXML() on Xpath results
<?php // Continued from example XML above. /* Search for <a><b><c> */ $result = $xml->xpath('/a/b/c'); while(list( , $node) = each($result)) { echo $node->asXML(); // <c>text</c> and <c>stuff</c> } ?>

SimpleXMLElement->attributes

(no version information, might be only in CVS)

SimpleXMLElement->attributes -- Identifies an element's attributes

Description

SimpleXMLElement simplexml_element->attributes ( [string data] )

This function provides the attributes and values defined within an xml tag.

Nota: SimpleXML possiede regole per aggiungere proprietà iterative a diversi metodi. Queste non possono essere visualizzate con var_dump() o qualsiasi altra cosa che possa esaminare gli oggetti.

Esempio 1. Interpret an XML string
<?php $string = <<<XML <a> <foo name="one" game="lonely">1</foo> </a> XML; $xml = simplexml_load_string($string); foreach($xml->foo[0]->attributes() as $a => $b) { echo $a,'="',$b,"\"\n"; } ?>
This script will display:
name="one" game="lonely"

SimpleXMLElement->children

(no version information, might be only in CVS)

SimpleXMLElement->children -- Finds children of given node

Description

SimpleXMLElement simplexml_element->children ( [string nsprefix] )

This method finds the children of the element of which it is a member. The result follows normal iteration rules.

Nota: SimpleXML possiede regole per aggiungere proprietà iterative a diversi metodi. Queste non possono essere visualizzate con var_dump() o qualsiasi altra cosa che possa esaminare gli oggetti.

Esempio 1. Traversing a children() pseudo-array

<?php
$xml = simplexml_load_string(
'<person>
 <child role="son">
  <child role="daughter"/>
 </child>
 <child role="daughter">
  <child role="son">
   <child role="son"/>
  </child>
 </child>
</person>');

foreach ($xml->children() as $second_gen) {
    echo ' The person begot a ' . $second_gen['role'];

    foreach ($second_gen->children() as $third_gen) {
        echo ' who begot a ' . $third_gen['role'] . ';';
    
        foreach ($third_gen->children() as $fourth_gen) {
            echo ' and that ' . $third_gen['role'] .
                ' begot a ' . $fourth_gen['role'];
        }
    }
}
?>

This script will output:

The person begot a son who begot a daughter; The person
begot a daughter who begot a son; and that son begot a son

SimpleXMLElement->xpath

(no version information, might be only in CVS)

SimpleXMLElement->xpath -- Runs Xpath query on XML data

Description

array SimpleXMLElement->xpath ( string path )

The xpath method searches the SimpleXML node for children matching the Xpath path. It always returns an array of SimpleXMLElement objects.

Esempio 1. Xpath
<?php $string = <<<XML <a> <b> <c>text</c> <c>stuff</c> </b> <d> <c>code</c> </d> </a> XML; $xml = simplexml_load_string($string); /* Search for <a><b><c> */ $result = $xml->xpath('/a/b/c'); while(list( , $node) = each($result)) { echo '/a/b/c: ',$node,"\n"; } /* Relative paths also work... */ $result = $xml->xpath('b/c'); while(list( , $node) = each($result)) { echo 'b/c: ',$node,"\n"; } ?>
This script will display:
/a/b/c: text /a/b/c: stuff b/c: text b/c: stuff
Notice that the two results are equal.

simplexml_import_dom

(PHP 5)

simplexml_import_dom -- Get a SimpleXMLElement object from a DOM node.

Description

SimpleXMLElement simplexml_import_dom ( DOMNode node [, string class_name] )

This function takes a node of a DOM document and makes it into a SimpleXML node. This new object can then be used as a native SimpleXML element. If any errors occur, it returns FALSE.

Esempio 1. Import DOM

<?php
$dom = new domDocument;
$dom->loadXML('<books><book><title>blah</title></book></books>');
if (!$dom) {
    echo 'Error while parsing the document';
    exit;
}

$s = simplexml_import_dom($dom);

echo $s->book[0]->title; // blah
?>

simplexml_load_file

(PHP 5)

simplexml_load_file -- Interprets an XML file into an object

Description

object simplexml_load_file ( string filename [, string class_name [, int options]] )

This function will convert the well-formed XML document in the file specified by filename to an object of class SimpleXMLElement. If any errors occur during file access or interpretation, the function returns FALSE.

You may use the optional class_name parameter so that simplexml_load_file() will return an object of the specified class. That class should extend the SimpleXMLElement class.

Since PHP 5.1.0 and Libxml 2.6.0, you may also use the options parameter to specify additional Libxml parameters.

Nota: Libxml 2 unescapes the URI, so if you want to pass e.g. b&c as the URI parameter a, you have to call simplexml_load_file(rawurlencode('http://example.com/?a=' . urlencode('b&c'))). Since PHP 5.1.0 you don't need to do this because PHP will do it for you.

Esempio 1. Interpret an XML document
<?php // The file test.xml contains an XML document with a root element // and at least an element /[root]/title. if (file_exists('test.xml')) { $xml = simplexml_load_file('test.xml'); var_dump($xml); } else { exit('Failed to open test.xml.'); } ?>
This script will display, on success:
SimpleXMLElement Object ( [title] => Example Title ... )
At this point, you can go about using $xml->title and any other elements.

simplexml_load_string

(PHP 5)

simplexml_load_string -- Interprets a string of XML into an object

Description

object simplexml_load_string ( string data [, string class_name [, int options]] )

This function will take the well-formed xml string data and return an object of class SimpleXMLElement with properties containing the data held within the xml document. If any errors occur, it returns FALSE.

You may use the optional class_name parameter so that simplexml_load_string() will return an object of the specified class. That class should extend the SimpleXMLElement class.

Since PHP 5.1.0 and Libxml 2.6.0, you may also use the options parameter to specify additional Libxml parameters.

Esempio 1. Interpret an XML string
<?php $string = <<<XML <?xml version='1.0'?> <document> <title>Forty What?</title> <from>Joe</from> <to>Jane</to> <body> I know that's the answer -- but what's the question? </body> </document> XML; $xml = simplexml_load_string($string); var_dump($xml); ?>
This script will display:
SimpleXMLElement Object ( [title] => Forty What? [from] => Joe [to] => Jane [body] => I know that's the answer -- but what's the question? )
At this point, you can go about using $xml->body and such.

CXXXVII. Funzioni per SNMP

Introduzione

Requisiti

Per potere utilizzare le funzioni SNMP su un sistema Unix, occorre installare il pacchetto NET SNMP. Sui sistemi Windows, invece, le funzioni SNMP sono disponibili soltanto su NT e non sui sistemi Windows 95 e 98.

Installazione

Attenzione: per potere usare il pacchetto UCD SNMP, occorre definire NO_ZEROLENGTH_COMMUNITY a 1 prima di compilarlo. Dopo avere configurato UCD SNMP, occorre editare il file config.h, cercare NO_ZEROLENGTH_COMMUNITY e decommentare la linea #define. Alla fine si deve ottenere:
#define NO_ZEROLENGTH_COMMUNITY 1
Ora si può compilare PHP con --with-snmp[=DIR].

Se durante l'uso dei comandi SNMP dovessero comparire degli errori di "segmentation fault", non seguire le istruzioni precedenti. Se non si desidera ricompilare il pacchetto UCD SNMP, si può optare per compilare PHP con l'opzione --enable-ucd-snmp-hack che aggira questo problema.

La distribuzione per Windows contiene i file di supporto per SNMP nella directory mibs. Questa directory dovrebbe esse spostata in DRIVE:\usr\mibs, dove DRIVE deve essere sostituito con la lettera del disco su cui è installato il PHP, ad esempio c:\usr\mibs

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Tipi di risorse

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

SNMP_VALUE_LIBRARY (integer)
SNMP_VALUE_PLAIN (integer)
SNMP_VALUE_OBJECT (integer)
SNMP_BIT_STR (integer)
SNMP_OCTET_STR (integer)
SNMP_OPAQUE (integer)
SNMP_NULL (integer)
SNMP_OBJECT_ID (integer)
SNMP_IPADDRESS (integer)
SNMP_COUNTER (integer)
SNMP_UNSIGNED (integer)
SNMP_TIMETICKS (integer)
SNMP_UINTEGER (integer)
SNMP_INTEGER (integer)
SNMP_COUNTER64 (integer)

Sommario
snmp_get_quick_print -- Restituisce il valore corrente per il parametro quick_print della libreria UCD
snmp_get_valueretrieval -- Return the method how the SNMP values will be returned
snmp_read_mib -- Reads and parses a MIB file into the active MIB tree
snmp_set_enum_print -- Return all values that are enums with their enum value instead of the raw integer
snmp_set_oid_numeric_print -- Return all objects including their respective object id within the specified one
snmp_set_quick_print -- Setta il valore di quick_print
snmp_set_valueretrieval -- Specify the method how the SNMP values will be returned
snmpget -- Preleva un oggetto SNMP
snmpgetnext -- Fetch a SNMP object
snmprealwalk -- Restituisce tutti gli oggetti compresi i rispettivi ID di oggetto
snmpset -- Valorizza un oggetto SNMP
snmpwalk -- Scarica tutti gli oggetti SNMP da un agente
snmpwalkoid -- Richiesta dell'albero delle informazioni di una macchina di rete

snmp_get_quick_print

(PHP 3 >= 3.0.8, PHP 4, PHP 5)

snmp_get_quick_print -- Restituisce il valore corrente per il parametro quick_print della libreria UCD

Descrizione

bool snmp_get_quick_print ( void )

La funzione restituisce il valore del parametro quick_print della libreria UCD. Per default quick_print è settato ad off.
Esempio 1. Esempio di snmp_get_quick_print()
<?php $quickprint = snmp_get_quick_print(); ?>

void snmp_set_quick_print ( bool quick_print )

La funzione setta il valore del parametro quick_print della libreria UCD SNMP. Quando è attivo (1), la libreria SNMP restituisce valori 'quick printed'. Ciò significa che saranno visualizzati solo i valori. Quando quick_print non è attivo (default), la libreria UCD SNMP visualizzerà informazioni extra tra i quali il tipo del valore (per esempio IpAddress oppure OID). Inoltre, se quick_print non è abilitato, la libreria visualizza il valore esadecimale per tutte le stringhe di tre caratteri o meno.

L'attivazione di quick_print viene spesso usata quando l'informazione restuita viene utilizzata piuttosto che visualizzata.

<?php
snmp_set_quick_print(0);
$a = snmpget("127.0.0.1", "public", ".1.3.6.1.2.1.2.2.1.9.1");
echo "$a< br />\n";
snmp_set_quick_print(1);
$a = snmpget("127.0.0.1", "public", ".1.3.6.1.2.1.2.2.1.9.1");
echo "$a<br />\n";
?>

Il primo valore visualizzato può essere 'Timeticks: (0) 0:00:00.00', mentre con quick_print abilitato sarebbe stato '0:00:00.00'.

Per default la libreria UCD SNMP restituisce valori discorsivi, mentre quick_print viene usato per avere solo il valore.

Attualmente le stringhe sono restituite con apici aggiuntivi, questo sarà corretto in una release successiva.

La funzione snmp_set_quick_print() è disponibile soltanto con l'uso della libreria UCD SNMP. Questa funzione non è disponibile nella libreria SNMP per Windows.

snmp_set_valueretrieval

(PHP 4 >= 4.3.3, PHP 5)

snmp_set_valueretrieval -- Specify the method how the SNMP values will be returned

Description

void snmp_set_valueretrieval ( int method )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

snmpget

(PHP 3, PHP 4, PHP 5)

snmpget -- Preleva un oggetto SNMP

Descrizione

string snmpget ( string hostname, string community, string object_id [, int timeout [, int retries]] )

La funzione restituisce il valore di un oggetto SNMP se ha successo, altrimenti FALSE se si verificano errori

La funzione snmpget(), viene utilizzata per leggere il valore dell'oggetto SNMP specificato da object_id. L'agente SNMP a cui accedere viene specificato nel parametro hostname, mentre la comunità viene indicata in community.

<?php
$syscontact = snmpget("127.0.0.1", "public", "system.SysContact.0");
?>

snmpgetnext

(PHP 5)

snmpgetnext -- Fetch a SNMP object

Description

string snmpgetnext ( string host, string community, string object_id [, int timeout [, int retries]] )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

snmprealwalk

(PHP 3 >= 3.0.8, PHP 4, PHP 5)

snmprealwalk -- Restituisce tutti gli oggetti compresi i rispettivi ID di oggetto

Descrizione

array snmprealwalk ( string host, string community, string object_id [, int timeout [, int retries]] )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

snmpset

(PHP 3 >= 3.0.12, PHP 4, PHP 5)

snmpset -- Valorizza un oggetto SNMP

Descrizione

bool snmpset ( string hostname, string community, string object_id, string type, mixed value [, int timeout [, int retries]] )

Setta il valore di un specifico oggetto SNMP. La funzione restituisce TRUE se ha successo, FALSE se si verifica un errore.

La funzione snmpset() viene usata per settare il valore dell'oggetto SNMP indicato dal parametro object_id. L'agente SNMP viene indicato nel parametro hostname e la comunità viene specificata nel parametro community.

snmpwalk

(PHP 3, PHP 4, PHP 5)

snmpwalk -- Scarica tutti gli oggetti SNMP da un agente

Descrizione

array snmpwalk ( string hostname, string community, string object_id [, int timeout [, int retries]] )

La funzione restituisce un array con i valori degli oggetti SNMP utilizzando object_id come punto di partenza, oppure FALSE se si verifica un errore.

La funzione snmpwalk() viene utilizzata per leggere tutti i valori dall'agente SNMP specificato nel parametro hostname. Il parametro Community specifica la comunità per l'agente. Con l'impostazione a NULL del parametro object_id si indica la radice dell'albero degli oggetti SNMP, pertanto saranno restituiti nell'array tutti gli oggetti dell'albero. Viceversa se si indica un valore per object_id, sarranno restituiti tutti gli oggetti sottostanti object_id.

<?php
$a = snmpwalk("127.0.0.1", "public", ""); 
?>

L'esempio precedente mostra come recuperare tutti gli oggetti SNMP dall'agente attivo sulla macchina locale. Tramite un loop (illustrato di seguito) si può accedere a tutti i valori.

<?php
for ($i=0; $i < count($a); $i++) {
    echo $a[$i];
}
?>

snmpwalkoid

(PHP 3 >= 3.0.8, PHP 4, PHP 5)

snmpwalkoid -- Richiesta dell'albero delle informazioni di una macchina di rete

Descrizione

array snmpwalkoid ( string hostname, string community, string object_id [, int timeout [, int retries]] )

La funzione restituisce un array associativo contenente gli id degli oggetti ed il loro rispettivo valore usando l'oggetto indicato in object_id come radice. Se si verificano degli errori la funzione restituisce FALSE.

La funzione snmpwalkoid() viene utilizzata per leggere gli id di tutti gli oggetti SNMP ed i relativi valori da un agente SNMP presente sul server indicato da hostname. La comunità viene specificata nel parametro community. Con l'impostazione a NULL del parametro object_id si indica la radice dell'albero degli oggetti SNMP, pertanto saranno restituiti nell'array tutti gli oggetti dell'albero. Viceversa se si indica un valore per object_id, sarranno restituiti tutti gli oggetti sottostanti a object_id.

La presenza delle due funzioni snmpwalkoid() e snmpwalk() ha ragioni storiche. Sono presenti entrambe per compatibilità con il passato.

<?php
$a = snmpwalkoid("127.0.0.1", "public", ""); 
?>

L'esempio precedente mostra come recuperare tutti gli oggetti SNMP dall'agente attivo sulla macchina locale. Tramite un loop (illustrato di seguito) si può accedere a tutti i valori.

<?php
for (reset($a); $i = key($a); next($a)) {
    echo "$i: $a[$i]<br />\n";
}
?>

CXXXVIII. SOAP Functions

Introduzione

The SOAP extension can be used to write SOAP Servers and Clients. It supports subsets of SOAP 1.1, SOAP 1.2 and WSDL 1.1 specifications.

Requisiti

This extension makes use of the GNOME xml library. Download and install this library. You will need at least libxml-2.5.4.

Installazione

This extension is only available if PHP was configured with --enable-soap.

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

Tabella 1. SOAP Configuration Options

Name	Default	Changeable	Changelog
soap.wsdl_cache_enabled	"1"	PHP_INI_ALL	Available since PHP 5.0.0.
soap.wsdl_cache_dir	"/tmp"	PHP_INI_ALL	Available since PHP 5.0.0.
soap.wsdl_cache_ttl	"86400"	PHP_INI_ALL	Available since PHP 5.0.0.

Per maggiori dettagli sulle costanti PHP_INI_* vedere Appendice G.

Breve descrizione dei parametri di configurazione.

soap.wsdl_cache_enabled boolean: Enables or disables the WSDL caching feature.
soap.wsdl_cache_dir string: Sets the directory name where the SOAP extension will put cache files.
soap.wsdl_cache_ttl int: Sets the number of seconds (time to live) that cached files will be used instead the originals.

Classi predefinite

SoapClient

Costruttori

SoapClient->__construct() - constructs a new SoapClient object

Metodi

SoapClient->__call() - Calls a SOAP function (deprecated)
SoapClient->__doRequest() - Performs a SOAP request
SoapClient->__getFunctions() - Returns list of SOAP functions
SoapClient->__getLastRequest() - Returns last SOAP request
SoapClient->__getLastRequestHeaders() - Returns last SOAP request headers
SoapClient->__getLastResponse() - Returns last SOAP response
SoapClient->__getLastResponseHeaders() - Returns last SOAP response headers
SoapClient->__getTypes() - Returns list of SOAP types
SoapClient->__setCookie() - Sets the cookie that will be sent with the SOAP request
SoapClient->__soapCall() - Calls a SOAP function

SoapFault

Costruttori

SoapFault->__construct() - construct a new SoapFault object

SoapHeader

SoapHeader is a special low-level class for passing or returning SOAP headers. It's just a data holder and it does not have any special methods except its constructor. It can be used in the SoapClient->__soapCall() method to pass a SOAP header or in a SOAP header handler to return the header in a SOAP response.

Costruttori

SoapHeader->__construct() - construct a new SoapHeader object

SoapParam

SoapParam is a special low-level class for naming parameters and returning values in non-WSDL mode. It's just a data holder and it does not have any special methods except its constructor.

Costruttori

SoapParam->__construct() - construct a new SoapParam object

SoapServer

Costruttori

SoapServer->__construct() - construct a new SoapServer object

Metodi

SoapServer->addFunction() - Adds one or several functions those will handle SOAP requests
SoapServer->fault() -
SoapServer->getFunctions() - Returns list of defined functions
SoapServer->handle() - Handles a SOAP request
SoapServer->setClass() - Sets class which will handle SOAP requests
SoapServer->setPersistence() - Sets persistence mode of SoapServer

SoapVar

SoapVar is a special low-level class for encoding parameters and returning values in non-WSDL mode. It's just a data holder and does not have any special methods except the constructor. It's useful when you want to set the type property in SOAP request or response.

Costruttori

SoapVar->__construct() - construct a new SoapVar object

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

SOAP_1_1 (integer)
SOAP_1_2 (integer)
SOAP_PERSISTENCE_SESSION (integer)
SOAP_PERSISTENCE_REQUEST (integer)
SOAP_FUNCTIONS_ALL (integer)
SOAP_ENCODED (integer)
SOAP_LITERAL (integer)
SOAP_RPC (integer)
SOAP_DOCUMENT (integer)
SOAP_ACTOR_NEXT (integer)
SOAP_ACTOR_NONE (integer)
SOAP_ACTOR_UNLIMATERECEIVER (integer)
SOAP_COMPRESSION_ACCEPT (integer)
SOAP_COMPRESSION_GZIP (integer)
SOAP_COMPRESSION_DEFLATE (integer)
UNKNOWN_TYPE (integer)
XSD_STRING (integer)
XSD_BOOLEAN (integer)
XSD_DECIMAL (integer)
XSD_FLOAT (integer)
XSD_DOUBLE (integer)
XSD_DURATION (integer)
XSD_DATETIME (integer)
XSD_TIME (integer)
XSD_DATE (integer)
XSD_GYEARMONTH (integer)
XSD_GYEAR (integer)
XSD_GMONTHDAY (integer)
XSD_GDAY (integer)
XSD_GMONTH (integer)
XSD_HEXBINARY (integer)
XSD_BASE64BINARY (integer)
XSD_ANYURI (integer)
XSD_ANYXML (integer): Added in PHP 5.1.0.
XSD_QNAME (integer)
XSD_NOTATION (integer)
XSD_NORMALIZEDSTRING (integer)
XSD_TOKEN (integer)
XSD_LANGUAGE (integer)
XSD_NMTOKEN (integer)
XSD_NAME (integer)
XSD_NCNAME (integer)
XSD_ID (integer)
XSD_IDREF (integer)
XSD_IDREFS (integer)
XSD_ENTITY (integer)
XSD_ENTITIES (integer)
XSD_INTEGER (integer)
XSD_NONPOSITIVEINTEGER (integer)
XSD_NEGATIVEINTEGER (integer)
XSD_LONG (integer)
XSD_INT (integer)
XSD_SHORT (integer)
XSD_BYTE (integer)
XSD_NONNEGATIVEINTEGER (integer)
XSD_UNSIGNEDLONG (integer)
XSD_UNSIGNEDINT (integer)
XSD_UNSIGNEDSHORT (integer)
XSD_UNSIGNEDBYTE (integer)
XSD_POSITIVEINTEGER (integer)
XSD_NMTOKENS (integer)
XSD_ANYTYPE (integer)
SOAP_ENC_OBJECT (integer)
SOAP_ENC_ARRAY (integer)
XSD_1999_TIMEINSTANT (integer)
XSD_NAMESPACE (string)
XSD_1999_NAMESPACE (string)

Sommario
is_soap_fault -- Checks if SOAP call was failed
SoapClient->__call() -- Calls a SOAP function (deprecated)
SoapClient->__construct() -- SoapClient constructor
SoapClient->__doRequest() -- Performs a SOAP request
SoapClient->__getFunctions() -- Returns list of SOAP functions
SoapClient->__getLastRequest() -- Returns last SOAP request
SoapClient->__getLastRequestHeaders() -- Returns last SOAP request headers
SoapClient->__getLastResponse() -- Returns last SOAP response.
SoapClient->__getLastResponseHeaders() -- Returns last SOAP response headers.
SoapClient->__getTypes() -- Returns list of SOAP types
SoapClient->__setCookie() -- Sets the cookie that will be sent with the SOAP request
SoapClient->__soapCall() -- Calls a SOAP function
SoapFault->__construct() -- SoapFault constructor
SoapHeader->__construct() -- SoapHeader constructor
SoapParam->__construct() -- SoapParam constructor
SoapServer->addFunction() -- Adds one or several functions those will handle SOAP requests
SoapServer->__construct() -- SoapServer constructor
SoapServer->fault() -- Issue SoapServer fault indicating an error
SoapServer->getFunctions() -- Returns list of defined functions
SoapServer->handle() -- Handles a SOAP request
SoapServer->setClass() -- Sets class which will handle SOAP requests
SoapServer->setPersistence() -- Sets persistence mode of SoapServer
SoapVar->__construct() -- SoapVar constructor
use_soap_error_handler -- Set whether to use the SOAP error handler and return the former value

is_soap_fault

(PHP 5)

is_soap_fault -- Checks if SOAP call was failed

Descrizione

bool is_soap_fault ( mixed obj )

This function is useful when you like to check if the SOAP call failed, but don't like to use exceptions. To use it you must create a SoapClient object with the exceptions option set to zero or FALSE. In this case, the SOAP method will return a special SoapFault object which encapsulates the fault details (faultcode, faultstring, faultactor and faultdetails).

If exceptions is not set then SOAP call will throw an exception on error. is_soap_fault() checks if the given parameter is a SoapFault object.

Elenco dei parametri

obj: The tested object.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 1. is_soap_fault() example
<?php $client = new SoapClient("some.wsdl", array('exceptions' => 0)); $result = $client->SomeFunction(); if (is_soap_fault($result)) { trigger_error("SOAP Fault: (faultcode: {$result->faultcode}, faultstring: {$result->faultstring})", E_ERROR); } ?>

Esempio 2. SOAP's standard method for error reporting is exceptions
<?php try { $client = new SoapClient("some.wsdl"); $result = $client->SomeFunction(/* ... */); } catch (SoapFault $fault) { trigger_error("SOAP Fault: (faultcode: {$fault->faultcode}, faultstring: {$fault->faultstring})", E_ERROR); } ?>

Vedere anche:

SoapClient->__call()

(no version information, might be only in CVS)

SoapClient->__call() -- Calls a SOAP function (deprecated)

Descrizione

class SoapClient {

mixed __call ( string function_name, array arguments [, array options [, array input_headers [, array output_headers]]] )

}

This method is deprecated. Use SoapClient->__soapCall() instead of it.

SoapClient->__construct()

(no version information, might be only in CVS)

SoapClient->__construct() -- SoapClient constructor

Descrizione

class SoapClient {

__construct ( mixed wsdl [, array options] )

}

This constructor creates SoapClient objects in WSDL or non-WSDL mode.

Elenco dei parametri

wsdl

URI of the WSDL file or NULL if working in non-WSDL mode.

options

An array of options. If working in WSDL mode, this parameter is optional. If working in non-WSDL mode, you must set the location and uri options, where location is the URL to request and uri is the target namespace of the SOAP service.

The style and use options only work in non-WSDL mode. In WSDL mode, they come from the WSDL file.

The soap_version option specifies whether to use SOAP 1.1, or SOAP 1.2 client.

For HTTP authentication, you may use the login and password options. For making an HTTP connection through a proxy server, use the options proxy_host, proxy_port, proxy_login and proxy_password. For HTTPS client certificate authentication use local_cert and passphrase options.

The compression option allows to use compression of HTTP SOAP requests and responses.

The encoding option defines internal character encoding. This option does not change the encofing of SOAP requests (it is always utf-8), but converts strings into it.

The classmap option can be used to map some WSDL types to PHP classes. This option must be an array with WSDL types as keys and names of PHP classes as values.

The trace and exceptions options are useful for debuging purpose.

Esempi

Esempio 1. SoapClient examples
<?php $client = new SoapClient("some.wsdl"); $client = new SoapClient("some.wsdl", array('soap_version' => SOAP_1_2)); $client = new SoapClient("some.wsdl", array('login' => "some_name", 'password' => "some_password")); $client = new SoapClient("some.wsdl", array('proxy_host' => "localhost", 'proxy_port' => 8080)); $client = new SoapClient("some.wsdl", array('proxy_host' => "localhost", 'proxy_port' => 8080, 'proxy_login' => "some_name", 'proxy_password' => "some_password")); $client = new SoapClient("some.wsdl", array('local_cert' => "cert_key.pem")); $client = new SoapClient(null, array('location' => "http://localhost/soap.php", 'uri' => "http://test-uri/")); $client = new SoapClient(null, array('location' => "http://localhost/soap.php", 'uri' => "http://test-uri/", 'style' => SOAP_DOCUMENT, 'use' => SOAP_LITERAL)); $client = new SoapClient("some.wsdl", array('compression' => SOAP_COMPRESSION_ACCEPT | SOAP_COMPRESSION_GZIP)); $server = new SoapClient("some.wsdl", array('encoding'=>'ISO-8859-1')); class MyBook { public $title; public $author; } $server = new SoapClient("books.wsdl", array('classmap' => array('book' => "MyBook"))); ?>

SoapClient->__doRequest()

(no version information, might be only in CVS)

SoapClient->__doRequest() -- Performs a SOAP request

Descrizione

class SoapClient {

string __doRequest ( string request, string location, string action, int version )

}

Performs SOAP request over HTTP.

This method can be overridden in subclasses to implement different transport layers, perform additional XML processing or other purpose.

Elenco dei parametri

request: The XML SOAP request.
location: The URL to request.
action: The SOAP action.
action: The SOAP version.

Valori restituiti

The XML SOAP response.

Esempi

Esempio 1. Some examples
<?php function Add($x,$y) { return $x+$y; } class LocalSoapClient extends SoapClient { function __construct($wsdl, $options) { parent::__construct($wsdl, $options); $this->server = new SoapServer($wsdl, $options); $this->server->addFunction('Add'); } function __doRequest($request, $location, $action, $version) { ob_start(); $this->server->handle($request); $response = ob_get_contents(); ob_end_clean(); return $response; } } $x = new LocalSoapClient(NULL,array('location'=>'test://', 'uri'=>'http://testuri.org')); var_dump($x->Add(3,4)); ?>

SoapClient->__getFunctions()

(no version information, might be only in CVS)

SoapClient->__getFunctions() -- Returns list of SOAP functions

Descrizione

class SoapClient {

array __getFunctions ( void )

}

Returns the list of SOAP functions.

Nota: This function works only in WSDL mode.

Valori restituiti

The list of SOAP functions.

Esempi

Esempio 1. SoapClient->__getFunctions() example
<?php $client = SoapClient("some.wsdl"); var_dump($client->__getFunctions()); ?>

Vedere anche:

SoapClient->__getLastRequest()

(no version information, might be only in CVS)

SoapClient->__getLastRequest() -- Returns last SOAP request

Descrizione

class SoapClient {

string __getLastRequest ( void )

}

Nota: This method works only if the SoapClient object was created with the trace option.

Valori restituiti

The last SOAP request.

Esempi

Esempio 1. SoapClient->__getLastRequest() example
<?php $client = SoapClient("some.wsdl", array('trace' => 1)); $result = $client->SomeFunction(); echo "REQUEST:\n" . $client->__getLastRequest() . "\n"; ?>

Vedere anche:

SoapClient->__getLastRequestHeaders()

SoapClient->__getLastResponse()

SoapClient->__getLastResponseHeaders()

SoapClient->__getLastRequestHeaders()

(no version information, might be only in CVS)

SoapClient->__getLastRequestHeaders() -- Returns last SOAP request headers

Descrizione

class SoapClient {

string __getLastRequestHeaders ( void )

}

Nota: This method works only if the SoapClient object was created with the trace option.

Valori restituiti

The last SOAP request headers.

Vedere anche:

SoapClient->__getLastRequest()

SoapClient->__getLastResponse()

SoapClient->__getLastResponseHeaders()

SoapClient->__getLastResponse()

(no version information, might be only in CVS)

SoapClient->__getLastResponse() -- Returns last SOAP response.

Descrizione

class SoapClient {

string __getLastResponse ( void )

}

Nota: This method works only if the SoapClient object was created with the trace option.

Valori restituiti

The last SOAP response.

Esempi

Esempio 1. SoapClient->__getLastResponse() example
<?php $client = SoapClient("some.wsdl", array('trace' => 1)); $result = $client->SomeFunction(); echo "RESPONSE:\n" . $client->__getLastResponse() . "\n"; ?>

Vedere anche:

SoapClient->__getLastResponseHeaders()

SoapClient->__getLastRequest()

SoapClient->__getLastRequestHeaders()

SoapClient->__getLastResponseHeaders()

(no version information, might be only in CVS)

SoapClient->__getLastResponseHeaders() -- Returns last SOAP response headers.

Descrizione

class SoapClient {

string __getLastResponseHeaders ( void )

}

Nota: This method works only if the SoapClient object was created with the trace option.

Valori restituiti

The last SOAP response headers.

Vedere anche:

SoapClient->__getLastResponse()

SoapClient->__getLastRequest()

SoapClient->__getLastRequestHeaders()

SoapClient->__getTypes()

(no version information, might be only in CVS)

SoapClient->__getTypes() -- Returns list of SOAP types

Descrizione

class SoapClient {

array __getTypes ( void )

}

This function works only in WSDL mode.

Valori restituiti

The list of SOAP types.

Esempi

Esempio 1. SoapClient->__getTypes() example
<?php $client = new SoapClient("some.wsdl"); var_dump($client->__getTypes()); ?>

Vedere anche:

SoapClient->__setCookie()

(no version information, might be only in CVS)

SoapClient->__setCookie() -- Sets the cookie that will be sent with the SOAP request

Descrizione

class SoapClient {

void __setCookie ( string name [, string value] )

}

Defines a cookie to be sent along with the SOAP requests.

Nota: Calling this method will affect all following calls to SoapClient methods.

Elenco dei parametri

name: The name of the cookie.
value: The value of the cookie. If not specified, the cookie will be deleted.

Valori restituiti

No value is returned.

SoapClient->__soapCall()

(no version information, might be only in CVS)

SoapClient->__soapCall() -- Calls a SOAP function

Descrizione

class SoapClient {

mixed __soapCall ( string function_name [, array arguments [, array options [, mixed input_headers [, array &output_headers]]]] )

}

This is a low level API function that is used to make a SOAP call. Usually, in WSDL mode, you can simply call SOAP functions as SoapClient methods. This method useful in non-WSDL mode when soapaction is unknown, uri differs from the default or when sending and/or receiving SOAP Headers.

On error, a call to a SOAP function can cause PHP to throw exceptions or return a SoapFault object if exceptions are disabled. To check if the function call failed to catch the SoapFault exceptions, check the result with is_soap_fault().

Valori restituiti

SOAP functions may return one, or multiple values. If only one value is returned by the SOAP function, the return value of __soapCall will be a simple value (e.g. an integer, a string, etc). If multiple values are returned, __soapCall will return an associative array of named output parameters.

Esempi

Esempio 1. SoapClient->__soapCall() Examples
<?php $client = new SoapClient("some.wsdl"); $client->SomeFunction($a, $b, $c); $client->__soapCall("SomeFunction", array($a, $b, $c)); $client->__soapCall("SomeFunction", array($a, $b, $c), NULL, new SoapHeader(), $output_headers); $client = new SoapClient(null, array('location' => "http://localhost/soap.php", 'uri' => "http://test-uri/")); $client->SomeFunction($a, $b, $c); $client->__soapCall("SomeFunction", array($a, $b, $c)); $client->__soapCall("SomeFunction", array($a, $b, $c), array('soapaction' => 'some_action', 'uri' => 'some_uri')); ?>

Vedere anche:

SoapHeader->__construct()

is_soap_fault()

SoapFault->__construct()

(no version information, might be only in CVS)

SoapFault->__construct() -- SoapFault constructor

Descrizione

class SoapFault {

__construct ( string faultcode, string faultstring [, string faultactor [, mixed detail [, string faultname [, SoapHeader headerfault]]]] )

}

This class is useful when you would like to send SOAP fault responses from the PHP handler. faultcode, faultstring, faultactor and details are standard elements of SOAP Fault;

Elenco dei parametri

faultcode: The error code of the SoapFault.
faultstring: The error message of the SoapFault.
faultactor: A string identifying the actor that caused the error.
detail
faultname: Can be used to select the proper fault encoding from WSDL.
headerfault: Can be used during SOAP header handling to report an error in the response header.

Esempi

Esempio 1. Some examples
<?php function test($x) { return new SoapFault("Server", "Some error message"); } $server = new SoapServer(null, array('uri' => "http://test-uri/")); $server->addFunction("test"); $server->handle(); ?>

It is possible to use PHP exception mechanism to throw SOAP Fault.

Esempio 2. Some examples
<?php function test($x) { throw new SoapFault("Server", "Some error message"); } $server = new SoapServer(null, array('uri' => "http://test-uri/")); $server->addFunction("test"); $server->handle(); ?>

Vedere anche:

is_soap_fault()

SoapHeader->__construct()

(no version information, might be only in CVS)

SoapHeader->__construct() -- SoapHeader constructor

Descrizione

class SoapHeader {

__construct ( string namespace, string name [, mixed data [, bool mustUnderstand [, mixed actor]]] )

}

Constructs a new SoapHeader object.

Elenco dei parametri

namespace: The namespace of the SOAP header element.
name: The name of the SOAP header element.
data: A SOAP header's content. It can be a PHP value or a SoapVar object.
mustUnderstand: Value of the mustUnderstand attribute of the SOAP header element.
actor: Value of the actor attribute of the SOAP header element.

Esempi

Esempio 1. Some examples
<?php $client = new SoapClient(null, array('location' => "http://localhost/soap.php", 'uri' => "http://test-uri/")); $client->__call("echoVoid", null, null, new SoapHeader('http://soapinterop.org/echoheader/', 'echoMeStringRequest', 'hello world')); ?>

Vedere anche:

(no version information, might be only in CVS)

SoapParam->__construct() -- SoapParam constructor

Descrizione

class SoapParam {

__construct ( mixed data, string name )

}

Constructs a new SoapParam object.

Elenco dei parametri

data: The data to pass or return. You can pass this parameter directly as PHP value, but in this case it will be named as paramN and the SOAP Service may not understand it.
name: The parameter name.

Esempi

Esempio 1. Some examples
<?php $client = new SoapClient(null,array('location' => "http://localhost/soap.php", 'uri' => "http://test-uri/")); $client->SomeFunction(new SoapParam($a, "a"), new SoapParam($b, "b"), new SoapParam($c, "c")); ?>

Vedere anche:

SoapServer->addFunction()

(no version information, might be only in CVS)

SoapServer->addFunction() -- Adds one or several functions those will handle SOAP requests

Descrizione

class SoapServer {

void addFunction ( mixed functions )

}

Exports one or more functions for remote clients.

Elenco dei parametri

functions

To export one function, pass the function name into this parameter as a string.

To export several functions, pass an array of function names.

To export all the functions, pass a special constant SOAP_FUNCTIONS_ALL.

Nota: functions must receive all input arguments in the same order as defined in the WSDL file (They should not receive any output parameters as arguments) and return one or more values. To return several values they must return an array with named output parameters.

Valori restituiti

No value is returned.

Esempi

Esempio 1. Some examples
<?php function echoString($inputString) { return $inputString; } $server->addFunction("echoString"); function echoTwoStrings($inputString1, $inputString2) { return array("outputString1" => $inputString1, "outputString2" => $inputString2); } $server->addFunction(array("echoString", "echoTwoStrings")); $server->addFunction(SOAP_FUNCTIONS_ALL); ?>

Vedere anche:

SoapServer->setClass()

SoapServer->__construct()

(no version information, might be only in CVS)

SoapServer->__construct() -- SoapServer constructor

Descrizione

class SoapServer {

__construct ( mixed wsdl [, array options] )

}

This constructor allows the creation of SoapServer objects in WSDL or non-WSDL mode.

Elenco dei parametri

wsdl: If you want the WSDL mode, you must set this to the URI of a WSDL file. In the other case, you must set this to NULL and set the uri option.
options: Allow setting a default SOAP version (soap_version), internal character encoding (encoding), and actor URI (actor). The classmap option can be used to map some WSDL types to PHP classes. This option must be an array with WSDL types as keys and names of PHP classes as values.

Esempi

Esempio 1. Some examples
<?php $server = new SoapServer("some.wsdl"); $server = new SoapServer("some.wsdl", array('soap_version' => SOAP_1_2)); $server = new SoapServer("some.wsdl", array('actor' => "http://example.org/ts-tests/C")); $server = new SoapServer("some.wsdl", array('encoding'=>'ISO-8859-1')); $server = new SoapServer(null, array('uri' => "http://test-uri/")); class MyBook { public $title; public $author; } $server = new SoapServer("books.wsdl", array('classmap' => array('book' => "MyBook"))); ?>

SoapServer->fault()

(no version information, might be only in CVS)

SoapServer->fault() -- Issue SoapServer fault indicating an error

Descrizione

class SoapServer {

void fault ( string code, string string [, string actor [, mixed details [, string name]]] )

}

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Vedere anche:

SoapServer->getFunctions()

(no version information, might be only in CVS)

SoapServer->getFunctions() -- Returns list of defined functions

Descrizione

class SoapServer {

array getFunctions ( void )

}

This method returns the list of all functions added by SoapServer->addFunction() or SoapServer->setClass().

Valori restituiti

The list of all functions.

Esempi

Esempio 1. Some examples
<?php $server = new SoapServer(NULL, array("uri" => "http://test-uri")); $server->addFunction(SOAP_FUNCTIONS_ALL); if ($_SERVER["REQUEST_METHOD"] == "POST") { $server->handle(); } else { echo "This SOAP server can handle following functions: "; $functions = $server->getFunctions(); foreach($functions as $func) { echo $func . "\n"; } } ?>

Vedere anche:

SoapServer->addFunction()

SoapServer->setClass()

SoapServer->handle()

(no version information, might be only in CVS)

SoapServer->handle() -- Handles a SOAP request

Descrizione

class SoapServer {

void handle ( [string soap_request] )

}

Processes a SOAP request, calls necessary functions, and sends a response back.

Elenco dei parametri

soap_request: The SOAP request. If this argument is omitted, the request is supposed to be in the $HTTP_RAW_POST_DATA PHP variable.

Valori restituiti

No value is returned.

Esempi

Esempio 1. Some examples
<?php function test($x) { return $x; } $server = new SoapServer(null, array('uri' => "http://test-uri/")); $server->addFunction("test"); $server->handle(); ?>

Vedere anche:

SoapServer->setClass()

(no version information, might be only in CVS)

SoapServer->setClass() -- Sets class which will handle SOAP requests

Descrizione

class SoapServer {

void setClass ( string class_name [, mixed args [, mixed ...]] )

}

Exports all methods from specified class.

The object can be made persistent across request for a given PHP session with the SoapServer->setPersistence() method.

Elenco dei parametri

class_name: The name of the exported class.
args: These optional parameters will be passed to the default class constructor during object creation.

Valori restituiti

No value is returned.

Esempi

Esempio 1. Some examples
<?php class foo { function foo() { } } $server->setClass("foo"); class bar { function bar($x, $y) { } } $server->setClass("bar", $arg1, $arg2); ?>

Vedere anche:

SoapServer->addFunction()

SoapServer->setPersistence()

(no version information, might be only in CVS)

SoapServer->setPersistence() -- Sets persistence mode of SoapServer

Descrizione

class SoapServer {

void setPersistence ( int mode )

}

This function allows saving data between requests in a PHP session. It works only with a server that exports functions from a class with SoapServer->setClass().

Elenco dei parametri

mode: One of the SOAP_PERSISTENCE_XXX constants.

Valori restituiti

No value is returned.

Esempi

Esempio 1. Some examples
<?php $server->setPersistence(SOAP_PERSISTENCE_SESSION); $server->setPersistence(SOAP_PERSISTENCE_REQUEST); ?>

Vedere anche:

SoapServer->setClass()

SoapVar->__construct()

(no version information, might be only in CVS)

SoapVar->__construct() -- SoapVar constructor

Descrizione

class SoapVar {

__construct ( mixed data, int encoding [, string type_name [, string type_namespace [, string node_name [, string node_namespace]]]] )

}

Constructs a new SoapVar object.

Elenco dei parametri

data: The data to pass or return.
encoding: The encoding ID, one of the XSD_... constants.
type_name: The type name.
type_namespace: The type namespace.
node_name: The XML node name.
node_namespace: The XML node namespace.

Esempi

Esempio 1. Some examples
<?php class SOAPStruct { function SOAPStruct($s, $i, $f) { $this->varString = $s; $this->varInt = $i; $this->varFloat = $f; } } $client = new SoapClient(null, array('location' => "http://localhost/soap.php", 'uri' => "http://test-uri/")); $struct = new SOAPStruct('arg', 34, 325.325); $soapstruct = new SoapVar($struct, SOAP_ENC_OBJECT, "SOAPStruct", "http://soapinterop.org/xsd"); $client->echoStruct(new SoapParam($soapstruct, "inputStruct")); ?>

Vedere anche:

use_soap_error_handler

(PHP 5)

use_soap_error_handler -- Set whether to use the SOAP error handler and return the former value

Descrizione

bool use_soap_error_handler ( [bool handler] )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

CXXXIX. Funzioni relative ai Socket

Introduzione

Questa estensione implementa una interfaccia a basso livello verso i socket, fornendo la possibilità di agire sia come server sia come client.

Per un esempio di una interfaccia generica lato client, vedere stream_socket_client(), stream_socket_server(), fsockopen() e pfsockopen().

Per l'utilizzo di queste funzioni, è importante ricordare che molte di esse hanno il medesimo nome della loro controparte in C, ma spesso hanno dichiarazioni differenti. Ricordarsi di leggere la descrizione per evitare confusione.

Per chi non ha familiarità con la programmazione dei socket, può trovare utili informazioni nelle pagine del manuale di Unix, ed inoltre sul web si può trovare diversi tutorial sulla programmazione dei socket in C, molti dei quali possono essere utilizzati, con lievi modifiche, nella programmazione dei socket in PHP. Il link Unix Socket FAQ può essere un buon punto di partenza.

Avvertimento

Requisiti

Non sono necessarie librerie esterne per utilizzare questo modulo.

Installazione

Le funzioni relative ai socket qui descritte sono parte di una estensione del PHP che occorre abilitare durante la fase di compila usando l'opzione --enable-sockets del comando configure.

Nota: Il supporto all'IPv6 è stato aggiunto in PHP 5.0.0.

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

AF_UNIX (integer)
AF_INET (integer)
AF_INET6 (integer)
SOCK_STREAM (integer)
SOCK_DGRAM (integer)
SOCK_RAW (integer)
SOCK_SEQPACKET (integer)
SOCK_RDM (integer)
MSG_OOB (integer)
MSG_WAITALL (integer)
MSG_PEEK (integer)
MSG_DONTROUTE (integer)
SO_DEBUG (integer)
SO_REUSEADDR (integer)
SO_KEEPALIVE (integer)
SO_DONTROUTE (integer)
SO_LINGER (integer)
SO_BROADCAST (integer)
SO_OOBINLINE (integer)
SO_SNDBUF (integer)
SO_RCVBUF (integer)
SO_SNDLOWAT (integer)
SO_RCVLOWAT (integer)
SO_SNDTIMEO (integer)
SO_RCVTIMEO (integer)
SO_TYPE (integer)
SO_ERROR (integer)
SOL_SOCKET (integer)
PHP_NORMAL_READ (integer)
PHP_BINARY_READ (integer)
SOL_TCP (integer)
SOL_UDP (integer)

Errori dei socket

L'estensione dei socket è stata scritta per fornire una pratica interfaccia ai potenti socket BSD. Si noti che le funzioni girano correttamente sia su sistemi Unix sia su sistemi Win32. Quasi tutte le funzioni dei socket possono fallire in certe situazioni e quindi generare un messaggio di tipo E_WARNING per descrivere l'errore. Qualche volta ciò non accade secondo le aspettative dello sviluppatore. Ad esempio la funzione socket_read() improvvisamente può generare un messaggio di E_WARNING a causa di una interruzione inaspettata della connessione. E' prassi comune sopprimere i messaggi di warning con l'operatore @ ed intercettare il codice dell'errore utilizzando la funzione socket_last_error(). Si può anche richiamare la funzione socket_strerror() con questo codice di errore per avere un testo descrittivo del problema. Per maggiori dettagli vedere la descrizione delle funzioni.

Nota: I messaggi E_WARNING generati dal modulo dei socket sono in inglese, mentre i messaggi di errore recuperati dipendono dalle correnti impostazioni locali (LC_MESSAGES):
Warning - socket_bind() unable to bind address [98]: Die Adresse wird bereits verwendet

Esempi

Esempio 1. Esempio di programma con i socket: semplice server TCP/IP
Questo esempio illustra un semplice server. Occorre modificare le variabili address e port per adeguarle ai parametri della macchina su cui sarà eseguito. Ci si può connettere al server con un comando simile a telnet 192.168.1.53 10000 (dove l'indirizzo e la porta devono essere uguali a quanto indicato nel setup). Qualsiasi lettera sarà digitata, verrà visualizzata sul server e sul client. Per disconnettersi, digitare 'quit'.
#!/usr/local/bin/php -q <?php error_reporting(E_ALL); /* Si indica allo script di non uscire mentre attende una connessione */ set_time_limit(0); /* Abilita lo scarico dell'output così si è in grado di vedere cosa passa * non appena arrivano i dati al server. */ ob_implicit_flush(); $address = '192.168.1.53'; $port = 10000; if (($sock = socket_create(AF_INET, SOCK_STREAM, SOL_TCP)) < 0) { echo "socket_create() fallito: motivo: " . socket_strerror($sock) . "\n"; } if (($ret = socket_bind($sock, $address, $port)) < 0) { echo "socket_bind() fallito: motivo: " . socket_strerror($ret) . "\n"; } if (($ret = socket_listen($sock, 5)) < 0) { echo "socket_listen() fallito: motivo: " . socket_strerror($ret) . "\n"; } do { if (($msgsock = socket_accept($sock)) < 0) { echo "socket_accept() fallito: motivo: " . socket_strerror ($msgsock) . "\n"; break; } /* Invio delle istruzioni */ $msg = "\nBenvenuti al server di test in PHP. \n" . "Per uscire, digitare 'quit'. Per chiudere il server digitare 'shutdown'.\n"; socket_write($msgsock, $msg, strlen($msg)); do { if (FALSE === ($buf = socket_read($msgsock, 2048, PHP_NORMAL_READ))) { echo "socket_read() fallito: motivo: " . socket_strerror($ret) . "\n"; break 2; } if (!$buf = trim($buf)) { continue; } if ($buf == 'quit') { break; } if ($buf == 'shutdown') { socket_close($msgsock); break 2; } $talkback = "PHP: Testo scritto '$buf'.\n"; socket_write($msgsock, $talkback, strlen $talkback)); echo "$buf\n"; } while (true); socket_close($msgsock); } while (true); socket_close($sock); ?>

Esempio 2. Esempio di programma con i socket: semplice client TCP/IP
In questo esempio sarà illustrato un semplice client HTTP. Questo, molto semplicemente, si collega ad un server, invia una richiesta HEAD, visualizza la risposta ed esce.
<?php error_reporting(E_ALL); echo "<h2>Connessione TCP/IP </h2>\n"; /* Ottiene la porta per il servizio WWW. */ $service_port = getservbyname('www', 'tcp'); /* Ottiene l'indirizzo IP per il server cercato. */ $address = gethostbyname('www.php.net'); /* Crea un socket TCP/IP. */ $socket = socket_create(AF_INET, SOCK_STREAM, SOL_TCP); if ($socket < 0) { echo "socket_create() fallito: motivo: " . socket_strerror($socket) . "\n"; } else { echo "OK.\n"; } echo "Tentativo di connessione a '$address' sulla porta '$service_port'..."; $result = socket_connect($socket, $address, $service_port); if ($result < 0) { echo "socket_connect() fallito.\nMotivo: ($result) " . socket_strerror($result) . "\n"; } else { echo "OK.\n"; } $in = "HEAD / HTTP/1.1\r\n"; $in .= "Host: www.example.com\r\n"; $in .= "Connection: Close\r\n\r\n"; $out = ''; echo "Invio HTTP HEAD..."; socket_write($socket, $in, strlen ($in)); echo "OK.\n"; echo "Lettura della risposta:\n\n"; while ($out = socket_read($socket, 2048)) { echo $out; } echo "Chiusura del socket..."; socket_close($socket); echo "OK.\n\n"; ?>

Sommario
socket_accept -- Accetta una connessione su un socket
socket_bind -- Bind di un nome ad un socket
socket_clear_error -- Azzera gli erorri di un socket, oppure l'ultimo codice d'errore
socket_close -- Chiude una risorsa di tipo socket
socket_connect -- Inizia una connessione su un socket
socket_create_listen -- Apre un socket per accettare connessioni su una porta
socket_create_pair -- Crea una coppia di socket non distinguibili e li memorizza in una matrice
socket_create -- Crea un socket (punto terminale di una comunicazione).
socket_get_option -- Ottiene le opzioni per un socket
socket_getpeername -- Interroga il lato remoto di un dato socket per ottenere o la combinazione host/porta od un percorso Unix, in base al tipo di socket
socket_getsockname -- Interroga il lato locale di un dato socket e restituisce o la combinazione host/porta oppure un percorso Unix in base al tipo di socket
socket_last_error -- Restituisce l'ultimo errore su un socket.
socket_listen -- Attende una richiesta di connessione su un socket
socket_read -- Legge fino ad un massimo di byte predefiniti da un socket
socket_recv -- Riceve i dati da un socket collegato
socket_recvfrom -- Riceve i dati da un socket, che sia connesso o meno
socket_select -- Esegue la system call select() su un set di socket con un dato timeout
socket_send -- Invia i dati ad un socket collegato
socket_sendto -- Invia un messaggio ad un socket, a prescindere che sia connesso o meno
socket_set_block -- Sets blocking mode on a socket resource
socket_set_nonblock -- Attiva la modalità "nonblocking" per il descrittore di file fd
socket_set_option -- Valorizza le opzioni per un socket
socket_shutdown -- Chiude un socket in ricezione, in invio o in entrambi i sensi
socket_strerror -- Restituisce una stringa con la descrizione dell'errore.
socket_write -- Scrive su un socket.

socket_accept

(PHP 4 >= 4.1.0, PHP 5)

socket_accept -- Accetta una connessione su un socket

Descrizione

resource socket_accept ( resource socket )

Avvertimento

Dopo la creazione del socket socket con socket_create(), l'assegnazione di un nome con socket_bind(), e averlo messo in attesa di connessione con socket_listen(), con questa funzione si inizia ad accettare le richieste di connessione su quel socket. Una volta avuta una connessione, la funzione restituisce un nuovo socket che può essere usato per la comunicazione. Se vi sono diverse richieste di connessioni pendenti verrà utilizzata la prima. Viceversa se non vi sono richieste in attesa, la funzione socket_accept() si blocca in attesa di una richiesta. Se il socket è stato configurato "non-blocking" con socket_set_blocking() o con socket_set_nonblock(), la funzione restituirà FALSE.

La risorsa socket restituita da socket_accept() non può essere utilizzata per acquisire nuove connesioni. Per questo scopo occorre continuare ad usare il socket originale, indicato in socket, che rimane aperto.

La funzione restistuisce una risorsa di tipo socket se ha successo, oppure FALSE se si verifica un errore. Il codice di errore può essere recuperato chiamando la funzione socket_last_error(). Questo codice può essere passato a socket_strerror() per ottenere una descrizione dell'errore.

Vedere anche socket_bind(), socket_connect(), socket_listen(), socket_create() e socket_strerror().

socket_bind

(PHP 4 >= 4.1.0, PHP 5)

socket_bind -- Bind di un nome ad un socket

Descrizione

bool socket_bind ( resource socket, string address [, int port] )

La funzione socket_bind() esegue il bind del nome passato in indirizzo sul socket indicato da socket,

Elenco dei parametri

socket

Una valida risorsa di tipo socket creata da socket_create().

address

Se il socket appartiene alla famiglia AF_INET, il parametro address è un classico indirizzo IP (ad esempio 127.0.0.1)

Se il socket appartiene alla famiglia AF_UNIX, il parametro address indica il percorso di un socket nel dominio Unix (ad esempio /tmp/my.sock).

port (Optional)

Il parametro port, si utilizza soltanto con le connessioni tramite un socket di tipo AF_INET, ed indica quale porta sul server remoto si debba utilizzare per eseguire la connessione.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Il codice di errore può essere recuperato con socket_last_error(). Questo codice può essere passato alla funzione socket_strerror() per ottenere una descrizione dell'errore.

Esempi

Esempio 1. Utilizzo di socket_bind() per impostare un indirizzo sorgente
<?php // Crea il nuovo socket $sock = socket_create(AF_INET, SOCK_STREAM, SOL_TCP); // Un esempio di elenco di IP del proprio computer $sourceips['kevin'] = '127.0.0.1'; $sourceips['madcoder'] = '127.0.0.2'; // Bind degli indirizzi socket_bind($sock, $sourceips['madcoder']); // Connessione all'indirisso di destinazione socket_connect($sock, '127.0.0.1', 80); // Scrittura $request = 'GET / HTTP/1.1' . "\r\n" . 'Host: example.com' . "\r\n\r\n"; socket_write($sock, $request); // Chiusura socket_close($sock); ?>

Note

Nota: Questa funzione deve essere utilizzata sui socket prima di socket_connect().

Nota: Windows 9x/ME nota di compatibilità: socket_last_error() può restituire un codice di errore non valido se si tenta il bind del socket ad un indirizzo errato che non appartiene alla propria macchina.

Vedere anche:

socket_connect()

socket_listen()

socket_create()

socket_last_error()

socket_strerror()

socket_clear_error

(PHP 4 >= 4.2.0, PHP 5)

socket_clear_error -- Azzera gli erorri di un socket, oppure l'ultimo codice d'errore

Descrizione

void socket_clear_error ( [resource socket] )

Avvertimento

Questa funzione azzera il codice d'errore di un dato socket, oppure azzera l'ultimo errore globale accaduto nei socket.

Questa funzione permette esplicitamente di azzerare il valore del codice di errore sia di un socket sia dell'ultimo codice di errore globale dell'estensione. Questo può essere utile per rilevare, all'interno di una parte di applicazione, se si è verificato un errore o meno.

Vedere anche socket_last_error() e socket_strerror().

socket_close

(PHP 4 >= 4.1.0, PHP 5)

socket_close -- Chiude una risorsa di tipo socket

Descrizione

void socket_close ( resource socket )

Avvertimento

La funzione socket_close() chiude la risorsa socket indicata nel parametro socket.

Nota: La funzione socket_close() non può essere utilizzata con risorse di tipo file create con fopen(), popen(), fsockopen(), oppure pfsockopen(); essa è stata predisposta per i socket creati con socket_create() oppure socket_accept().

Vedere anche socket_bind(), socket_listen(), socket_create() e socket_strerror().

socket_connect

(PHP 4 >= 4.1.0, PHP 5)

socket_connect -- Inizia una connessione su un socket

Descrizione

bool socket_connect ( resource socket, string indirizzo [, int porta] )

Avvertimento

Apre una connessione usando la risorsa di tipo socket socket, la quale deve essere una risorsa di socket valida generata da socket_create().

Il parametro indirizzo può essere sia un classico indirizzo IP (ad esempio 127.0.0.1), se il socket appartiene alla famiglia AF_INET, sia il percorso di un socket nel dominio Unix, se il socket appartiene alla famiglia AF_UNIX.

Il parametro porta, utilizzato soltanto con le connessioni tramite un socket di tipo AF_INET, indica quale porta sul server remoto si debba utilizzare per eseguire la connessione.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento. Il codice di errore può essere recuperato con socket_last_error(). Questo codice può essere passato alla funzione socket_strerror() per ottenere una descrizione dell'errore.

Vedere anche socket_bind(), socket_listen(), socket_create(), socket_last_error() e socket_strerror().

socket_create_listen

(PHP 4 >= 4.1.0, PHP 5)

socket_create_listen -- Apre un socket per accettare connessioni su una porta

Descrizione

resource socket_create_listen ( int porta [, int backlog] )

Avvertimento

Questa funzione è stata concepita per rendere semplice il compito di creare un nuovo socket che sia in attesa di nuove connessioni.

La funzione socket_create_listen() crea una nuova risorsa socket di tipo AF_INET in attesa su una data porta in tutte le interfacce locali di una nuova connessione.

Il parametro backlog indica la lunghezza massima della coda delle connessioni pendenti. Come valore per backlog, può essere passata la costante SOMAXCONN, vedere socket_listen() per maggiori dettagli.

socket_create_listen() restituisce una nuova risorsa di tipo socket se ha successo, oppure FALSE su errore. Il codice dell'errore può essere recuperato con la funzione socket_last_error(). Questo codice può essere passato alla funzione socket_strerror() per ottenere una descrizione dell'errore.

Nota: Se si desidera creare un socket che sia in attesa solo su certe interfacce, occorre utilizzare socket_create(), socket_bind() e socket_listen().

Vedere anche socket_create(), socket_bind(), socket_listen(), socket_last_error() e socket_strerror().

socket_create_pair

(PHP 4 >= 4.1.0, PHP 5)

socket_create_pair -- Crea una coppia di socket non distinguibili e li memorizza in una matrice

Descrizione

bool socket_create_pair ( int domain, int type, int protocol, array &fd )

Avvertimento

La funzione socket_create_pair() crea due socket connessi ed indistinguibili e li memorizza in &fd. Questa funzione è comunemente utilizzate per l'IPC (InterProcess Communication, comunicazione tra processi).

Il parametro domain specifica la famiglia di protocolli da usare per il socket.

Tabella 1. Famiglie di indirizzi/protocolli disponibili

Dominio	Descrizione
AF_INET	Protocollo Internet basato su IPv4. Il TCP e l'UDP sono i protocolli più comuni di questa famiglia. Supportati solo in Windows.
AF_INET6	Protocollo Internet basato su IPv6. Il TCP e l'UDP sono i protocolli più comuni di questa famiglia. Supportati solo in Windows. IPv6 Internet based protocols. Supporto aggiunto in PHP 5.0.0.
AF_UNIX	Famiglia di protocolli per la comunicazione locale. Molto efficiente, basso overhead permettono un buon tipo di IPC (Interprocess Communication).

Il parametro type seleziona il tipo di comunicazione da utilizzare con il socket.

Tabella 2. Tipi di socket disponibili

Tipo	Descrizione
SOCK_STREAM	Fornisce una connessione sequenziale, affidabile e full-duplex. Può essere supportato un meccanismo di trasmissione fuori-banda. Il protocollo TCP è basato su questo tipo di socket.
SOCK_DGRAM	Supporta i datagrammi (privo di connessione, messaggi inaffidabili di una lunghezza massima prefissata). Il protocollo UDP è basato su questo tipo di socket.
SOCK_SEQPACKET	Fornisce una trasmissione di dati sequenziale, affidabile, bi-direzionale per i datagrammi di lunghezza massima prefissata; all'utilizzatore è richiesto di leggere l'intero pacchetto in ogni esecuzione della funzione di lettura dal socket.
SOCK_RAW	Fornisce un'accesso raw al protocollo di rete. Questo tipo di socket può essere utilizzato per costruire manualmente qualsiasi tipo di protocollo. Un comune utilizzo di questa tipologia di socket è la realizzazione di richieste ICMP (tipo il ping o traceroute).
SOCK_RDM	Fornisce un'interfaccia affidabile per i datagrammi ma non ne garantisce l'ordine. Probabilmente questo non è implementato nel vostro sistema operativo.

Il parametro protocol indica lo specifico protocollo nel domain indicato da usarsi con il socket restituito. Il valore opportuno può essere recuperato utilizzando getprotobyname(). Se il protocollo desiderato è il TCP o l'UDP, si possono utilizzare le corrispondenti costanti SOL_UDP e SOL_TCP.

Tabella 3. Protocolli comuni

Nome	Descrizione
icmp	L'Internet Control Message Protocol viene utilizzato principalmente dai gateway e dagli host per riportare errori nelle comunicazioni con datagrammi. Il comando "ping" (presente in quasi tutti i moderni sistemi operativi) è un esempio dell'applicazione di ICMP.
udp	Lo User Datagram Protocol è un protocollo privo di connessione, inaffidabile con record di lunghezza fissa. Per questo l'UDP richiede poco overhead di protocollo.
tcp	Il Transmission Control Protocol è un procotollo affidabile, basato sulla connessione, orientato al flusso, full duplex. Il TCP garantisce che tutti i pacchetti siano ricevuti nel medesimo ordine in cui siano stati inviati. Se un pacchetto viene perso durante la trasmissione, il TCP provvederà automaticamente alla ritrasmissione fino a quando l'host remoto non conferma la ricezione dello stesso. Per ragioni di affidabilità e di prestazioni, è il TCP stesso a decidere l'appropriata dimensione dei pacchetti del sottostante livello di datagrammi. Pertanto le applicazioni TCP devono permettere la parziale ritrasmissione di un record.

Esempio 1. Esempio di uso di socket_create_pair()
<?php $sockets = array(); $uniqid = uniqid(''); if (file_exists("/tmp/$uniqid.sock")) { die('Temporary socket already exists.'); } /* Setup socket pair */ if (!socket_create_pair(AF_UNIX, SOCK_STREAM, 0, $sockets)) { echo socket_strerror(socket_last_error()); } /* Send and Recieve Data */ if (!socket_write($sockets[0], "ABCdef123\n", strlen("ABCdef123\n"))) { echo socket_strerror(socket_last_error()); } if (!$data = socket_read($sockets[1], strlen("ABCdef123\n"), PHP_BINARY_READ)) { echo socket_strerror(socket_last_error()); } var_dump($data); /* Close sockets */ socket_close($sockets[0]); socket_close($sockets[1]); ?>

Esempio 2. Esempio di IPC con socket_create_pair()
<?php $ary = array(); $strone = 'Message From Parent.'; $strtwo = 'Message From Child.'; if (!socket_create_pair(AF_UNIX, SOCK_STREAM, 0, $ary)) { echo socket_strerror(socket_last_error()); } $pid = pcntl_fork(); if ($pid == -1) { echo 'Could not fork Process.'; } elseif ($pid) { /*parent*/ socket_close($ary[0]); if (!socket_write($ary[1], $strone, strlen($strone))) { echo socket_strerror(socket_last_error()); } if (socket_read($ary[1], strlen($strtwo), PHP_BINARY_READ) == $strtwo) { echo "Recieved $strtwo\n"; } socket_close($ary[1]); } else { /*child*/ socket_close($ary[1]); if (!socket_write($ary[0], $strtwo, strlen($strtwo))) { echo socket_strerror(socket_last_error()); } if (socket_read($ary[0], strlen($strone), PHP_BINARY_READ) == $strone) { echo "Recieved $strone\n"; } socket_close($ary[0]); } ?>

socket_create

(PHP 4 >= 4.1.0, PHP 5)

socket_create -- Crea un socket (punto terminale di una comunicazione).

Descrizione

resource socket_create ( int dominio, int tipo, int protocollo )

La funzione crea un punto terminale di una comunicazione (un socket) e restituisce una risorsa di tipo socket. In una tipica connessione di rete si hanno 2 sockets, uno con il ruolo di client e l'altro con il ruolo di server.

Il parametro dominio indica il dominio (famiglia di protocolli da usarsi per la comunicazione tra i sockets).

Tabella 1. Famiglie di indirizzi/protocolli disponibili

Dominio	Descrizione
AF_INET	Protocollo Internet basato su IPv4. TCP e UDP sono i protocolli più comuni di questa famiglia.
AF_INET6	Protocolli basati su IPv6. TCP ed UDP sono i protocolli più comuni di questa famiglia. Il supporto a questa famiglia è stato aggiunto in PHP 5.0.0.
AF_UNIX	Famiglia di protocolli per le comunicazioni locali. L'alta efficenza ed il basso overhead ne fanno una buona forma di IPC (comunicazione inter-processo).

Il parametro tipo indica il tipo di comunicazione da usare con il socket.

Tabella 2. Tipi di socket disponibili

Tipo	Descrizione
SOCK_STREAM	Fornisce una connessione sequenziale, affidabile e full-duplex. Può essere supportato un meccanismo di trasmissione fuori-banda. Il protocollo TCP è basato su questo tipo di socket.
SOCK_DGRAM	Supporta i datagrammi (privo di connessione, messaggi inaffidabili di una lunghezza massima prefissata). Il protocollo UDP è basato su questo tipo di socket.
SOCK_SEQPACKET	Fornisce una trasmissione di dati sequenziale, affidabile, bi-direzionale per i datagrammi di lunghezza massima prefissata; all'utilizzatore è richiesto di leggere l'intero pacchetto in ogni esecuzione della funzione di lettura dal socket.
SOCK_RAW	Fornisce un'accesso raw al protocollo di rete. Questo tipo di socket può essere utilizzato per costruire manualmente qualsiasi tipo di protocollo. Un comune utilizzo di questa tipologia di socket è la realizzazione di richieste ICMP (tipo il ping o traceroute).
SOCK_RDM	Fornisce un'interfaccia affidabile per i datagrammi ma non ne garantisce l'ordine. Probabilmente questo non è implementato nel vostro sistema operativo.

Il parametro protocollo indica lo specifico protocollo nel dominio indicato da usarsi con il socket restituito. Il valore opportuno può essere recuperato utilizzando getprotobyname(). Se il protocollo desiderato è il TCP o l'UDP, si possono utilizzare le corrispondenti costanti SOL_UDP e SOL_TCP.

Tabella 3. Protocolli comuni

Nome	Descrizione
icmp	L'Internet Control Message Protocol viene utilizzato principalmente dai gateway e dagli host per riportare errori nelle comunicazioni con datagrammi. Il comando "ping" (presente in quasi tutti i moderni sistemi operativi) è un esempio dell'applicazione di ICMP.
udp	Lo User Datagram Protocol è un protocollo privo di connessione, inaffidabile con record di lunghezza fissa. Per questo l'UDP richiede poco overhead di protocollo.
tcp	Il Transmission Control Protocol è un procotollo affidabile, basato sulla connessione, orientato al flusso, full duplex. Il TCP garantisce che tutti i pacchetti siano ricevuti nel medesimo ordine in cui siano stati inviati. Se un pacchetto viene perso durante la trasmissione, il TCP provvederà automaticamente alla ritrasmissione fino a quando l'host remoto non conferma la ricezione dello stesso. Per ragioni di affidabilità e di prestazioni, è il TCP stesso a decidere l'appropriata dimensione dei pacchetti del sottostante livello di datagrammi. Pertanto le applicazioni TCP devono permettere la parziale ritrasmissione di un record.

La funzione restituisce una risorsa di tipo socket se ha successo, oppure FALSE in caso di errore. In quest'ultimo caso si può ottenere il codice di errore tramite socket_last_error(). Tale codice può essere passato alla funzione socket_strerror() per ottenere una descrizione dell'errore.

Nota: Se si forniscono valori non validi per dominio o tipo, la funzione socket_create() imposta i parametri rispettivamente a AF_INET e SOCK_STREAM ed emette un messaggio di tipo E_WARNING.

Vedere anche socket_accept(), socket_bind(), socket_connect(), socket_listen(), socket_last_error() e socket_strerror().

socket_get_option

(PHP 4 >= 4.3.0, PHP 5)

socket_get_option -- Ottiene le opzioni per un socket

Descrizione

mixed socket_get_option ( resource socket, int level, int optname )

Avvertimento

La funzione socket_get_option() restituisce i valori per il parametro indicato in optname per il socket indicato da socket. La funzione restituisce FALSE se non riesce.

Il parametro level specifica a quale livello di protocollo risiede l'opzione cercata. Ad esempio, per recuperare le informzioni su opzioni a livello di socket, il parametro level deve essere impostato a SOL_SOCKET. Altri livelli tipo TCP, possono essere utilizzati specificando il numero del livello. I numeri dei livelli dei protocolli possono essere ottenuti tramite getprotobyname().

Tabella 1. Opzioni per i socket disponibili

Opzione	Descrizione
SO_DEBUG	Riporta informazioni per il debug.
SO_ACCEPTCONN	Indica se il socket è abilitato in ascolto.
SO_BROADCAST	Indica se sono supportate le trasmissioni dei messaggi di broadcast.
SO_REUSEADDR	Riporta se gli indirizzi locali possono essere riutilizzati.
SO_KEEPALIVE	Riporta se la connesisone deve essere mantenuta attiva tramite la trasmissione periodica di messaggi. Se il socket connesso non risponde a questi messaggi, la connessione viene interrotta ed i processi che stavano scrivendo in quel socket riceveranno il segnale SIGPIPE.
SO_LINGER	Indice se il `socket` debba ritardare il socket_close() se vi sono dati.
SO_OOBINLINE	Indica se il `socket` gestisce i dati fuori-banda.
SO_SNDBUF	Riporta le dimensioni del buffer di trasmissione.
SO_RCVBUF	Riporta le dimensioni del buffer di ricezione.
SO_ERROR	Restituisce informaizoni sugli stati di errore e li ripulisce.
SO_TYPE	Restituisce il tipo di`socket`.
SO_DONTROUTE	Indica se i messaggi in uscita ignorano i parametri standard di routing.
SO_RCVLOWAT	Indica il numero minimo di byte da processare da parte del `socket` per le operazioni di input (default 1).
SO_RCVTIMEO	Tempo di timeout per le operazioni di input.
SO_SNDLOWAT	Riporta il numero minimo di byte da processare da parte del `socket` per le operazioni di output.
SO_SNDTIMEO	Indica il tempo di timeout specificando il tempo che una funzione di output resti bloccata in attesa di potere inviare i dati.

Nota: Nelle versioni di PHP antecedenti la 4.3.0, questa funzione era chiamata socket_getopt().

socket_getpeername

(PHP 4 >= 4.1.0, PHP 5)

socket_getpeername -- Interroga il lato remoto di un dato socket per ottenere o la combinazione host/porta od un percorso Unix, in base al tipo di socket

Descrizione

bool socket_getpeername ( resource socket, string &indirizzo [, int &porta] )

Avvertimento

Se il socket dato è di tipo AF_INET oppure AF_INET6, socket_getpeername() restituisce l'indirizzo IP remoto nella notazione appropriata (ad esempio 127.0.0.1 oppure fe80::1) nel parametro indirizzo e, se presente il parametro opzionale porta, anche la porta associata.

Se il socket dato è di tipo AF_UNIX, socket_getpeername() restituirà un percorso Unix (ad esempio /var/run/daemon.sock) nel parametro indirizzo.

Nota: La funzione socket_getpeername() non dovrebbe essere usata con socket AF_UNIX creati da socket_accept(). Soltanto i socket creati con socket_connect() o un socket server primario conseguente alla chiamata di socket_bind() restituirà dei valori significativi.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento. socket_getpeername() può anche restituire FALSE se il tipo di socket non è AF_INET, AF_INET6 o AF_UNIX, in questo caso l'ultimo codice di errore del socket non viene aggiornato.

Vedere anche socket_getsockname(), socket_last_error() e socket_strerror().

socket_getsockname

(PHP 4 >= 4.1.0, PHP 5)

socket_getsockname -- Interroga il lato locale di un dato socket e restituisce o la combinazione host/porta oppure un percorso Unix in base al tipo di socket

Descrizione

bool socket_getsockname ( resource socket, string &indirizzo [, int &porta] )

Avvertimento

Se il socket dato è di tipo AF_INET oppure AF_INET6, socket_getsockname() restituisce l'indirizzo IP locale nella notazione appropriata (ad esempio 127.0.0.1 oppure fe80::1) nel parametro indirizzo e, se presente il parametro opzionale porta, anche la porta associata.

Se il socket dato è di tipo AF_UNIX, socket_getsockname() restituirà un percorso Unix (ad esempio /var/run/daemon.sock) nel parametro indirizzo.

Nota: La funzione socket_getsockname() non dovrebbe essere usata con socket AF_UNIX creati da socket_accept(). Soltanto i socket creati con socket_connect() o un socket server primario conseguente alla chiamata di socket_bind() restituirà dei valori significativi.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento. socket_getsockname() può anche restituire FALSE se il tipo di socket non è AF_INET, AF_INET6 o AF_UNIX, in questo caso l'ultimo codice di errore del socket non viene aggiornato.

Vedere anche socket_getpeername(), socket_last_error() e socket_strerror().

socket_last_error

(PHP 4 >= 4.1.0, PHP 5)

socket_last_error -- Restituisce l'ultimo errore su un socket.

Descrizione

int socket_last_error ( [resource socket] )

Avvertimento

Questa funzione restituisce il codice di errore di un socket.

Se a questa funzione si passa una risorsa di tipo socket, essa restituisce l'ultimo errore occorso in quel socket. Se, al contrario, si omette di indicare il socket, verrà restituito l'ultimo errore generato dalle funzioni dei socket. Il secondo caso è particolarmente utile per funzioni tipo socket_create(), che in caso di errore non restituiscono un socket, o socket_select(), che possono fallire per ragioni non direttamente collegate ad un particolare socket. Il codice di errore è utilizzabile dalla funzione socket_strerror() per ottenere un testo con la spiegazione del codice di errore dato.
<?php if (false == ($socket = @socket_create(AF_INET, SOCK_STREAM, SOL_TCP))) { die("Non si riesce a creare il socket, codice di errore: " . socket_last_error() . ",descrizione: " . socket_strerror(socket_last_error())); } ?>

Nota: socket_last_error() non rimuove il codice di errore, utilizzare socket_clear_error() per questo scopo.

socket_listen

(PHP 4 >= 4.1.0, PHP 5)

socket_listen -- Attende una richiesta di connessione su un socket

Descrizione

bool socket_listen ( resource socket [, int backlog] )

Avvertimento

Una volta creato il socket socket tramite la funzione socket_create(), ed eseguito il bind ad un nome con socket_bind(), lo si può mettere in ascolto di eventuali richieste di connessione su socket.

Nota: Il numero massimo, passato con il parametro backlog dipende fortemente dalla piattaforma sottostante. Su Linux questo viene troncato, senza avvisare, a SOMAXCONN. Su Win32, se viene passata la costante SOMAXCONN, il servizio sottostante responsabile dei socket valorizza backlog al massimo valore ragionevole. Non esiste un metodo standard per determinare il reale valore massimo su questa piattaforma.

La funzione socket_listen() è disponibile solo per i socket di tipo SOCK_STREAM o SOCK_SEQPACKET.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento. Il codice di errore può essere recuperato con socket_last_error(). Questo codice può essere passato a socket_strerror() per ottenere una spiegazione dell'errore.

Vedere anche socket_accept(), socket_bind(), socket_connect(), socket_create() e socket_strerror().

socket_read

(PHP 4 >= 4.1.0, PHP 5)

socket_read -- Legge fino ad un massimo di byte predefiniti da un socket

Descrizione

string socket_read ( resource socket, int lunghezza [, int tipo] )

Avvertimento

La funzione socket_read() legge un numero massimo di byte, indicato in lunghezza, da un socket socket creato dalla funzione socket_accept() oppure da socket_create(). In alternativa si possono usare i caratteri \n, \r o \0 per indicare la fine della lettura (in base al parametro tipo, vedere più avanti)

La funzione restituisce i dati come una stringa in caso di successo, FALSE su errore. Il codice di errore può essere recuperato con socket_last_error(). Questo codice può essere passato a socket_strerror() per ottenere una descrizione dell'errore.

Nota: socket_read() può restituire una stringa di lunghezza zero ("") indicante la fine della comunicazione (ad esempio il server remoto ha chiuso la connessione).

Il parametro opzionale tipo può assumere i seguenti valori:

PHP_BINARY_READ - usa la funzione di sistema read(). Salvaguarda la lettura di dati binari (Default in PHP >= 4.1.0)
PHP_NORMAL_READ - ferma la lettura in presenza di \n oppure \r. (Default in PHP <= 4.0.6)

Vedere anche socket_accept(), socket_bind(), socket_connect(), socket_listen(), socket_last_error(), socket_strerror() e socket_write().

socket_recv

(PHP 4 >= 4.1.0, PHP 5)

socket_recv -- Riceve i dati da un socket collegato

Descrizione

int socket_recv ( resource socket, string &buf, int len, int flags )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

socket_recvfrom

(PHP 4 >= 4.1.0, PHP 5)

socket_recvfrom -- Riceve i dati da un socket, che sia connesso o meno

Descrizione

int socket_recvfrom ( resource socket, string &buf, int len, int flags, string &name [, int &port] )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

La funzione socket_recvfrom() gestisce i dati binari dal PHP 4.3.0

socket_select

(PHP 4 >= 4.1.0, PHP 5)

socket_select -- Esegue la system call select() su un set di socket con un dato timeout

Descrizione

int socket_select ( array lettura, array scrittura, array except, int tv_sec [, int tv_usec] )

Avvertimento

La funzione socket_select() accetta un array di socket e si mette in attesa di una variazione di stato su questi. Questa, derivando come background dai socket BSD, riconoscerà che questi array di risorse socket sono in realtà dei set di descrittori di file. Saranno monitorati 3 set di socket.

I socket indicati nell'array lettura, saranno monitorati in attesa dell'arrivo di caratteri disponibili per la lettura (più precisamente, per verificare che una lettura non sia bloccata, una risorsa socket viene definita pronta anche su fine file, in questo caso la funzione socket_read() restituirà una stringa di lunghezza zero).

I socket indicati nell'array di scrittura, sarranno monitorati per verificare che una scrittura non si blocchi.

I socket indicati nell'array except saranno monitorati per rilevare delle eccezioni.

Avvertimento

In uscita, gli array sarrano modificati in modo da indicare quale risorsa di tipo socket ha variato il proprio stato.

Non si è obbligati a passare tutti gli array a socket_select(). Se ne possono tralasciare, al loro posto utilizzare un array vuoto oppure NULL. Inoltre non si dimentichi che gli array sono passati per riferimento e che saranno modificati all'uscita dalla funzione socket_select().

Esempio 1. Esempio di socket_select()
<?php /* Preparo l'array di lettura */ $read = array($socket1, $socket2); $num_changed_sockets = socket_select($read, $write = NULL, $except = NULL, 0); if ($num_changed_sockets === false) { /* Gestione dell'errore */ } else if ($num_changed_sockets > 0) { /* Su almeno un socket è accaduto qualcosa di interessante */ } ?>

Nota: A causa delle limitazioni della versione attuale del Zend Engine, non è possibile passare direttamente una costante, ad esempio NULL, come parametro ad una funzione che si aspetti questo passato per riferimento. Si utilizzi, invece, una variabile temporanea oppura una espressione il cui membro di sinistra sia una variabile temporanea:
Esempio 2. Uso di NULL con socket_select()
<?php
socket_select($r, $w, $e = NULL, 0);  
?>

I parametri tv_sec ed tv_usec insieme indicano il timeout. Il timeout indica il limite superiore di tempo che deve trascorrere prima che la funzione socket_select() esca. tv_sec può essere a zero, ciò causa una uscita immediata di socket_select(). Ciò risulta utile nei casi di polling. Se tv_sec viene impostato a NULL (nessun timeout), la funzione resta in attesa per un tempo indefinito.

Se ha successo socket_select() restituisce il numero di risorse socket contenute nell'array modificato, tale valore può essere zero se scade il timeout prima che sia accaduto qualcosa. La funzione restituisce FALSE se si verifica un errore. Il codice di errore può essere recuperato tramite la funzione socket_last_error().

Nota: Si utilizzi l'operatore === quanto si eseguono dei test per rilevare un errore. Poichè la funzione socket_select() può restituire 0 il confronto eseguito con == sarebbe valutato come TRUE:
Esempio 3. Comprensione dei risultati di socket_select()
<?php
if (false === socket_select($r, $w, $e = NULL, 0)) {  
    echo "socket_select() failed, reason: " . socket_strerror(socket_last_error()) . "\n";  
}  
?>

Nota: Si presti attenzione alle implementazioni di certi socket che richiedono di essere gestiti molto attentamente. Alcune regole di base:
Si cerchi di utilizzare sempre socket_select() senza il timeout. Il programma non dovrebbe avere nulla da fare se non ci sono dati disponibili. Il codice basato sui timeout solitamente non è migrabile ed è difficile da testare.
Nei tre set, non inserire una risorsa socket di cui non si intende controllarne il risultato dopo la chiamata a socket_select(), e ne si intende rispondere in modo appropriato. Dopo la chiamata a socket_select(), occorre verificare tutti i socket in tutti gli array. Si deve scrivere su qualsiasi socket disponibile per la scrittura, e deve essere letto qualsiasi socket diponibile per la lettura.
Se si ha il ritorno della disponibilità di un socket, sia in lettura che in scrittura, non è detto che sia disponile per l'intero ammontare dei dati da scrivere/leggere. Occorre essere preparati a gestire il caso in cui la disponibilità sia limitata anche ad un solo byte.
Nella maggior parte delle implementazioni dei socket, l'unica eccezione catturata con il parametro except è l'arrivo di dati fuori banda.

Vedere anche socket_read(), socket_write(), socket_last_error() e socket_strerror().

socket_send

(PHP 4 >= 4.1.0, PHP 5)

socket_send -- Invia i dati ad un socket collegato

Descrizione

int socket_send ( resource socket, string buf, int len, int flags )

Avvertimento

La funzione socket_send() invia len bytes nel socket indicato da socket dal buffer buf

I valori di flags può essere una qualsiasi combinazione OR dei seguenti:

Tabella 1. valori possibili per flags

`0x1`	Tratta dati OOB (fuori banda)
`0x2`	Preleva il messaggio
`0x4`	Ignora il routing, usa l'interfaccia diretta
`0x8`	I dati comletano il record
`0x100`	I dati completano la transazione

Vedere anche socket_sendmsg() e socket_sendto().

socket_sendto

(PHP 4 >= 4.1.0, PHP 5)

socket_sendto -- Invia un messaggio ad un socket, a prescindere che sia connesso o meno

Descrizione

int socket_sendto ( resource socket, string buf, int len, int flags, string addr [, int port] )

Avvertimento

La funzione socket_sendto() invia len bytes dal buffer buf attraverso il socket socket alla porta port dell'indirizzo addr

Il valore ammessi per flags può essere uno dei seguenti:

Tabella 1. valori possibili per flags

`0x1`	Elabora dati OOB (fuori banda).
`0x2`	Preleva il messaggio in arrivo.
`0x4`	Ignora il routing, usa l'interfaccia diretta.
`0x8`	I dati completano il record.
`0x100`	I dati completano al transazione.

Esempio 1. Esempio di socket_sendto()

<?php
    $sh = socket_create(AF_INET, SOCK_STREAM, SOL_TCP);
    if (socket_bind($sh, '127.0.0.1', 4242)) {
        echo "Socket agganciato correttamente";
    }
    $buf = 'Test Message';
    $len = strlen($buf);
    if (socket_sendto($sh, $buf, $len, 0x100, '192.168.0.2', 4242) !== false) {
        echo "Messaggio inviato correttamente";
    }
    socket_close($sh);
?>

Vedere anche socket_send() e socket_sendmsg().

socket_set_block

(PHP 4 >= 4.2.0, PHP 5)

socket_set_block -- Sets blocking mode on a socket resource

Description

La funzione socket_strerror() utilizza come proprio parametro errno il codice di errore di un socket fornito da socket_last_error() e restituisce il corrispondente testo descrittivo. Questo rende più semplice piegare cosa è accaduto quando qualcosa non funziona; ad esempio, invece di dovere cercare in tutto il sistema un file che contenga la spiegazione di '-111', si può semplicemente passare il valore a socket_strerror(), e ottenere la spiegazione di ciò che è accaduto.

Esempio 1. Esempio di uso di socket_strerror()
<?php if (false == ($socket = @socket_create (AF_INET, SOCK_STREAM, SOL_TCP))) { echo "socket_create() fallito: motivo: " . socket_strerror (socket_last_error()) . "\n"; } if (false == (@socket_bind ($socket, '127.0.0.1', 80))) { echo "socket_bind() fallito: motivo: " . socket_strerror (socket_last_error($socket)) . "\n"; } ?>
Dall'esempio precedente (se non viene eseguito con i privilegi di root) ci si aspetta il seguente messaggio:
socket_bind() fallito: motivo: Permission denied

Vedere anche socket_accept(), socket_bind(), socket_connect(), socket_listen() e socket_create().

socket_write

(PHP 4 >= 4.1.0, PHP 5)

socket_write -- Scrive su un socket.

Descrizione

int socket_write ( resource socket, string buffer [, int lunghezza] )

Avvertimento

La funzione socket_write() scrive sul socket socket i dati tratti dal campo buffer.

Il parametro opzionale lunghezza può specificare un numero alternativo di bytes da scrivere nel socket. Se questa dimensione è maggiore della lunghezza di buffer, questa viene, in modo silenzioso, ridotta alla lunghezza di buffer.

La funzione restituisce il numero di bytes scritti con successo nel socket, oppure FALSE se si verifica un errore. Il codice di errore può essere rilevato con socket_last_error(). Passando questo codice alla funzione socket_strerror() si ottiene una spiegazione dell'errore.

Nota: socket_write() non scrive necessariamente tutti i byte da un dato buffer. E' ammesso che, in base alle dimensioni dei buffer della rete ecc., soltanto un certo ammontare di dati, anche un solo byte, sia scritto nel socket, nonostante il buffer sia di dimensioni maggiori. Si deve prestare attenzione a ciò per evitare di non inviare il resto dei dati.

Nota: E' regolare per la funzione socket_write() restituire zero, ciò significa che non è stato scritto alcun byte. Si utilizzi l'operatore === per testare il caso di FALSE nelle situazioni di errore.

Vedere anche socket_accept(), socket_bind(), socket_connect(), socket_listen(), socket_read() e socket_strerror().

CXL. Standard PHP Library (SPL) Functions

Introduzione

SPL is a collection of interfaces and classes that are meant to solve standard problems.

Suggerimento: A more detailed documentation of SPL can be found here.

Installazione

This extension is available and compiled by default in PHP 5.

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

RIT_LEAVES_ONLY (integer)
RIT_SELF_FIRST (integer)
RIT_CHILD_FIRST (integer)
CIT_CALL_TOSTRING (integer)
CIT_CATCH_GET_CHILD (integer)

Sommario
ArrayIterator::current -- Return current array entry
ArrayIterator::key -- Return current array key
ArrayIterator::next -- Move to next entry
ArrayIterator::rewind -- Rewind array back to the start
ArrayIterator::seek -- Seek to position
ArrayIterator::valid -- Check whether array contains more entries
ArrayObject::append -- Appends the value
ArrayObject::__construct -- Construct a new array object
ArrayObject::count -- Return the number of elements in the Iterator
ArrayObject::getIterator -- Create a new iterator from an ArrayObject instance
ArrayObject::offsetExists -- Returns whether the requested $index exists
ArrayObject::offsetGet -- Returns the value at the specified $index
ArrayObject::offsetSet -- Sets the value at the specified $index to $newval
ArrayObject::offsetUnset -- Unsets the value at the specified $index
CachingIterator::hasNext -- Check whether the inner iterator has a valid next element
CachingIterator::next -- Move the iterator forward
CachingIterator::rewind -- Rewind the iterator
CachingIterator::__toString -- Return the string representation of the current element
CachingIterator::valid -- Check whether the current element is valid
CachingRecursiveIterator::getChildren -- Return the inner iterator's children as a CachingRecursiveIterator
CachingRecursiveIterator::hasChildren -- Check whether the current element of the inner iterator has children
DirectoryIterator::__construct -- Constructs a new dir iterator from a path
DirectoryIterator::current -- Return this (needed for Iterator interface)
DirectoryIterator::getATime -- Get last access time of file
DirectoryIterator::getCTime -- Get inode modification time of file
DirectoryIterator::getChildren -- Returns an iterator for the current entry if it is a directory
DirectoryIterator::getFilename -- Return filename of current dir entry
DirectoryIterator::getGroup -- Get file group
DirectoryIterator::getInode -- Get file inode
DirectoryIterator::getMTime -- Get last modification time of file
DirectoryIterator::getOwner -- Get file owner
DirectoryIterator::getPath -- Return directory path
DirectoryIterator::getPathname -- Return path and filename of current dir entry
DirectoryIterator::getPerms -- Get file permissions
DirectoryIterator::getSize -- Get file size
DirectoryIterator::getType -- Get file type
DirectoryIterator::isDir -- Returns true if file is directory
DirectoryIterator::isDot -- Returns true if current entry is '.' or '..'
DirectoryIterator::isExecutable -- Returns true if file is executable
DirectoryIterator::isFile -- Returns true if file is a regular file
DirectoryIterator::isLink -- Returns true if file is symbolic link
DirectoryIterator::isReadable -- Returns true if file can be read
DirectoryIterator::isWritable -- Returns true if file can be written
DirectoryIterator::key -- Return current dir entry
DirectoryIterator::next -- Move to next entry
DirectoryIterator::rewind -- Rewind dir back to the start
DirectoryIterator::valid -- Check whether dir contains more entries
FilterIterator::current -- Get the current element value
FilterIterator::getInnerIterator -- Get the inner iterator
FilterIterator::key -- Get the current key
FilterIterator::next -- Move the iterator forward
FilterIterator::rewind -- Rewind the iterator
FilterIterator::valid -- Check whether the current element is valid
LimitIterator::getPosition -- Return the current position
LimitIterator::next -- Move the iterator forward
LimitIterator::rewind -- Rewind the iterator to the specified starting offset
LimitIterator::seek -- Seek to the given position
LimitIterator::valid -- Check whether the current element is valid
ParentIterator::getChildren -- Return the inner iterator's children contained in a ParentIterator
ParentIterator::hasChildren -- Check whether the inner iterator's current element has children
ParentIterator::next -- Move the iterator forward
ParentIterator::rewind -- Rewind the iterator
RecursiveDirectoryIterator::getChildren -- Returns an iterator for the current entry if it is a directory
RecursiveDirectoryIterator::hasChildren -- Returns whether current entry is a directory and not '.' or '..'
RecursiveDirectoryIterator::key -- Return path and filename of current dir entry
RecursiveDirectoryIterator::next -- Move to next entry
RecursiveDirectoryIterator::rewind -- Rewind dir back to the start
RecursiveIteratorIterator::current -- Access the current element value
RecursiveIteratorIterator::getDepth -- Get the current depth of the recursive iteration
RecursiveIteratorIterator::getSubIterator -- The current active sub iterator
RecursiveIteratorIterator::key -- Access the current key
RecursiveIteratorIterator::next -- Move forward to the next element
RecursiveIteratorIterator::rewind -- Rewind the iterator to the first element of the top level inner iterator
RecursiveIteratorIterator::valid -- Check whether the current position is valid
SimpleXMLIterator::current -- Return current SimpleXML entry
SimpleXMLIterator::getChildren -- Returns an iterator for the current entry if it is a SimpleXML object
SimpleXMLIterator::hasChildren -- Returns whether current entry is a SimpleXML object
SimpleXMLIterator::key -- Return current SimpleXML key
SimpleXMLIterator::next -- Move to next entry
SimpleXMLIterator::rewind -- Rewind SimpleXML back to the start
SimpleXMLIterator::valid -- Check whether SimpleXML contains more entries
class_implements -- Return the interfaces which are implemented by the given class
class_parents -- Return the parent classes of the given class
iterator_count -- Count the elements in an iterator
iterator_to_array -- Copy the iterator into an array
spl_classes -- Return available SPL classes

class: An object (class instance) or a string (class name).
autoload: Whether to allow this function to load the class automatically through the __autoload magic method. Defaults to TRUE.

Valori restituiti

Returns an array or FALSE on error.

Log delle modifiche

Versione	Descrizione
5.1.0	Added the option to pass the `class` parameter as a string. Added the `autoload` parameter.

Esempi

Esempio 1. class_implements() example
<?php interface foo { } class bar implements foo {} print_r(class_implements(new bar)); // since PHP 5.1 you may also specify the parameter as a string print_r(class_implements('bar')); function __autoload($class_name) { require_once $class_name . '.php'; } // use __autoload to load the 'not_loaded' class print_r(class_implements('not_loaded', true)); ?>
Il precedente esempio visualizzerà qualcosa simile a:
Array ( [foo] => foo ) Array ( [interface_of_not_loaded] => interface_of_not_loaded )

Vedere anche:

class_parents()

class_parents

(PHP 5)

class_parents -- Return the parent classes of the given class

Descrizione

array class_parents ( mixed class [, bool autoload] )

This function returns an array with the name of the parent classes of the given class.

Elenco dei parametri

class: An object (class instance) or a string (class name).
autoload: Whether to allow this function to load the class automatically through the __autoload magic method. Defaults to TRUE.

Valori restituiti

Returns an array or FALSE on error.

Log delle modifiche

Versione	Descrizione
5.1.0	Added the option to pass the `class` parameter as a string. Added the `autoload` parameter.

Esempi

Esempio 1. class_parents() example
<?php class foo { } class bar extends foo {} print_r(class_parents(new bar)); // since PHP 5.1 you may also specify the parameter as a string print_r(class_parents('bar')); function __autoload($class_name) { require_once $class_name . '.php'; } // use __autoload to load the 'not_loaded' class print_r(class_parents('not_loaded', true)); ?>
Il precedente esempio visualizzerà qualcosa simile a:
Array ( [foo] => foo ) Array ( [parent_of_not_loaded] => parent_of_not_loaded )

Vedere anche:

class_implements()

iterator_count

(PHP 5 >= 5.1.0RC1)

iterator_count -- Count the elements in an iterator

Description

int iterator_count ( IteratorAggregate iterator )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

iterator_to_array

(PHP 5 >= 5.1.0RC1)

iterator_to_array -- Copy the iterator into an array

Description

array iterator_to_array ( IteratorAggregate iterator )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

spl_classes

(PHP 5)

spl_classes -- Return available SPL classes

Description

array spl_classes ( void )

This function returns an array with the current available SPL classes.

Esempio 1. spl_classes() example
<?php print_r(spl_classes()); ?>
Il precedente esempio visualizzerà qualcosa simile a:
Array ( [ArrayObject] => ArrayObject [ArrayIterator] => ArrayIterator [CachingIterator] => CachingIterator [CachingRecursiveIterator] => CachingRecursiveIterator [DirectoryIterator] => DirectoryIterator [FilterIterator] => FilterIterator [LimitIterator] => LimitIterator [ParentIterator] => ParentIterator [RecursiveDirectoryIterator] => RecursiveDirectoryIterator [RecursiveIterator] => RecursiveIterator [RecursiveIteratorIterator] => RecursiveIteratorIterator [SeekableIterator] => SeekableIterator [SimpleXMLIterator] => SimpleXMLIterator )

CXLI. SQLite

Introduzione

Questo è un modulo per l'uso di SQLite Embeddable SQL Database Engine. SQLite è una libreria C che implementa al proprio interno un motore per database SQL. I programmi che compilano al proprio interno la libreria SQLite possono accedere ad un database senza dovere eseguire un processo RDBMS separato.

SQLite non è una libreria client che si deve collegare ad un qualche grosso server database. SQLite è il server. La libreria SQLite legge e scrive direttamente sul file del database.

Nota: Per maggiori informazioni vedere il sito web di SQLite (http://sqlite.org/).

Installazione

Leggere il file INSTALL allegato al pacchetto. Oppure utilizzare l'installatore PEAR con i parametri "pear install sqlite". La libreria SQLite è già inclusa. Non occorre installare altro software.

Gli utenti di Windows possono scaricare la versione DLL del module SQLite da qui: (php_sqlite.dll).

Da PHP 5, il modulo SQLite e il motore stesso saranno inclusi per default.

Requisiti

Per potere utilizzare questa funzioni, occorre compilare il PHP con il supporto per SQLite, oppure caricare dinamicamente il modulo da php.ini.

Tipi di risorse

SQLite utilizza due risorse. La prima è la connessione con il database, la seconda è il set di risultati.

Costanti predefinite

Le funzioni sqlite_fetch_array() e sqlite_current() utilizzano costanti per indicare i differenti tipi di matrici da restituire. Tali costanti sono:

Tabella 1. Costanti di SQLiteper scaricare le righe

costante	significato
SQLITE_ASSOC	Le colonne sono restituite in una matrice il cui indice è il nome del campo.
SQLITE_BOTH	Le colonne sono restituite in una matrice il cui indice è costituito sia dal nome del campo sia numero della posizione di questo nella riga.
SQLITE_NUM	Le colonne sono restituite in una matrice il cui indice è costituito dalla posizione del campo nella riga. La prima colonna parte da 0.

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

Tabella 2. Parametri di configurazione di SQLite

Nome	Default	Modificabile
sqlite.assoc_case	0	PHP_INI_ALL

Per maggiori dettagli e definizioni delle costanti PHP_INI_* vedere ini_set().

Breve descrizione dei parametri di configurazione.

sqlite.assoc_case int

Indica se utilizzare indici misti (0), solo maiuscole (1) oppure solo minuscoli (2).

Questa opzione è utile quando si ha necessità di avere compatibilità con altri database, nei quali i nomi delle colonne sono sempre restituiti o maiuscoli o minuscoli, a prescindere dalla definizione del campo nello schema del database.

La libreria SQLite restituisce i nomi delle colonne così come sono definiti (ovvero rispettando le maiuscole o le minuscole indicate nello schema). Quando si imposta sqlite.assoc_case a 0 si rispetta la definizione. Quando si imposta il parametro a 1 oppure a 2, il PHP converte i nomi rispettivamente in maiuscolo o minuscolo.

L'utilizzo di questa opzione comporta una lieve penalità nelle performance, ma è molto più veloce che convertire i nomi dallo script PHP.

Sommario
sqlite_array_query -- Esegue una query in un dato database e restituisce una matrice
sqlite_busy_timeout -- Imposta il timeout di 'in uso', o disabilita l'handle di 'in uso'
sqlite_changes -- Restituisce il numero di righe modificate dall'ultima istruzione SQL
sqlite_close -- Chiude un database SQLite
sqlite_column -- Scarica una riga dal set di risultati corrente
sqlite_create_aggregate -- Registra un aggregato UDF da utilizzare nelle istruzioni SQL
sqlite_create_function -- Registra una funzione utente "regolare" da utilizzare nelle istruzioni SQL
sqlite_current -- Scarica la riga corrente di un set di risultati in una matrice
sqlite_error_string -- Restituisce la descrizione testuale di un codice di errore
sqlite_escape_string -- Inserisce il carattere di escape in stringa da usarsi in una query
sqlite_exec -- ESegue una query priva di risultato in un dato database
sqlite_factory -- Apre un database SQLite e restituisce un oggetto SQLiteDatabase
sqlite_fetch_all -- Scarica tutte le righe di un risultato in una matrice di matrici
sqlite_fetch_array -- Scarica in una matrice la riga successiva da un set di risultati
sqlite_fetch_column_types -- Restituisce una matrice con il formato delle colonne di una tabella
sqlite_fetch_object -- Scarica i dati deti della riga successiva come oggetto
sqlite_fetch_single -- Scarica come stringa la prima colonna di un set di risultati
sqlite_fetch_string -- Alias di sqlite_fetch_single()
sqlite_field_name -- Restituisce il nome di un particolare campo
sqlite_has_more -- Restituisce se sono disponibili o meno ulteriori righe
sqlite_has_prev -- Indica se è disponibile o meno una riga precedente
sqlite_key -- Restituisce l'indice di riga corrente
sqlite_last_error -- Restituisce il codice di errore dell'ultimo errore accorso sul database
sqlite_last_insert_rowid -- Restituisce l'identificativo di riga dell'ultima riga inserita
sqlite_libencoding -- Restituisce la codifica della libreria SQLite
sqlite_libversion -- Restituisce la versione della libreria SQLite
sqlite_next -- Si sposta al successivo numero di riga
sqlite_num_fields -- Resituitsce il numero di campi da un set di risultati
sqlite_num_rows -- Restituisce il numero di righe da un set di risultati bufferizzato
sqlite_open -- Apre un database SQLite e crea il database se non esiste
sqlite_popen -- Apre una connessione persistente ad un database SQLite e crea il database se non esiste
sqlite_prev -- Si posiziona sulla riga precedente di un set di risultati
sqlite_query -- Esegue una query su un database e restituisce un puntatore al set di risultati
sqlite_rewind -- Si posiziona sulla prima riga
sqlite_seek -- Posizionamento su una data riga di un set di risultati bufferizzato
sqlite_single_query -- Esegue una query e restituisce o una matrice per ogni singola colonna o il valore della prima riga
sqlite_udf_decode_binary -- Decodifica dati binari passati come parametri in UDF
sqlite_udf_encode_binary -- Codifica i dati binari prima di restituirli da un UDF
sqlite_unbuffered_query -- Esegue una query senza scaricare e bufferizzare i dati
sqlite_valid -- Indica se una o più righe sono disponibili

sqlite_array_query

(PHP 5)

sqlite_array_query

(no version information, might be only in CVS)

SQLiteDatabase->arrayQuery -- Esegue una query in un dato database e restituisce una matrice

Descrizione

array sqlite_array_query ( resource dbhandle, string query [, int result_type [, bool decode_binary]] )

array sqlite_array_query ( string query, resource dbhandle [, int result_type [, bool decode_binary]] )

Versione ad oggetti (metodo):

class SQLiteDatabase {

array arrayQuery ( string query [, int result_type [, bool decode_binary]] )

}

sqlite_array_query() esegue una data query e restituisce un matrice con l'intero set di risultati. E' simile a sqlite_query() e a eseguiresqlite_fetch_array() per ogni riga. sqlite_array_query() è significativamente più veloce.

Suggerimento: Le migliori performance con sqlite_array_query() si ottengono con query che restituiscono fino a 45 righe. Se si ha più dati si raccomanda di scrivere una propria funzione e di utilizzare sqlite_unbuffered_query().

Elenco dei parametri

query: Query da eseguire.
dbhandle: Risorsa SQLite Database restituita da sqlite_open () quando usato in modo procedurale. Questo parametro non è richiesto nel metodo ad oggetti.
result_type: The optional result_type parameter accepts a constant and determines how the returned array will be indexed. Using SQLITE_ASSOC will return only associative indices (named fields) while SQLITE_NUM will return only numerical indices (ordinal field numbers). SQLITE_BOTH will return both associative and numerical indices. SQLITE_BOTH is the default for this function.
decode_binary: Quando decode_binary è impostato a TRUE (per default), il PHP decodificherà i dati binari se questi furono codificati con la funzione sqlite_escape_string(). Normalmente si dovrebbe lasciare inalterato il comportamento di default, a meno che non si debba intervenire su database creati da altre applicazioni SQLite.

Nota: Two alternative syntaxes are supported for compatibility with other database extensions (such as MySQL). The preferred form is the first, where the dbhandle parameter is the first parameter to the function.

Valori restituiti

Restituisce una matrice contenente tutti i risultati, oppure FALSE.

I nomi delle colonne restituiti da SQLITE_ASSOC e da SQLITE_BOTH saranno maiuscoli o minuscoli in base al valore del parametro di configurazione sqlite.assoc_case.

Esempi

Esempio 1. Stile procedurale
<?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']; } ?>

Esempio 2. Stile ad oggetti
<?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']; } ?>

Vedere anche:

sqlite_fetch_string()

sqlite_busy_timeout

(PHP 5)

sqlite_busy_timeout

(no version information, might be only in CVS)

SQLiteDatabase->busyTimeout -- Imposta il timeout di 'in uso', o disabilita l'handle di 'in uso'

Descrizione

void sqlite_busy_timeout ( resource dbhandle, int milliseconds )

Object oriented style (method):

class SQLiteDatabase {

void busyTimeout ( int milliseconds )

}

SImposta il tempo massimo che sqlite attenderà che un dbhandle diventi disponibile all'uso.

Elenco dei parametri

dbhandle

Risorsa SQLite Database restituita da sqlite_open () quando usato in modo procedurale. Questo parametro non è richiesto nel metodo ad oggetti.

milliseconds

Numero di millisecondi. Se il parametro è impostato a 0, l'handle di 'in uso' viene disattivato e sqlite ritornerà immediatamente con un errore SQLITE_BUSY se un'altro processo/thread ha bloccato il database per un aggiornamento.

Il PHP imposta per default il timeout di 'in uso' a 60 secondi durante l'apertura del database.

Nota: Ci sono mille (1000) millisecondi in un secondo.

Esempi

Esempio 1. Stile procedurale
<?php $dbhandle = sqlite_open('sqlitedb'); sqlite_busy_timeout($dbhandle, 10000); // set timeout to 10 seconds sqlite_busy_timeout($dbhandle, 0); // disable busy handler ?>

Esempio 2. Stile ad oggetti
<?php $dbhandle = new SQLiteDatabase('sqlitedb'); $dbhandle->busyTimeout(10000); // 10 seconds $dbhandle->busyTimeout(0); // disable ?>

Vedere anche:

sqlite_changes

(PHP 5)

sqlite_changes

(no version information, might be only in CVS)

SQLiteDatabase->changes -- Restituisce il numero di righe modificate dall'ultima istruzione SQL

Descrizione

int sqlite_changes ( resource dbhandle )

Versione ad oggetti (metodo):

class SQLiteDatabase {

int changes ( void )

}

Restituisce il numero di righe modificate dall'ultima istruzione SQL eseguita sul database referenziato da dbhandle.

Elenco dei parametri

dbhandle: Risorsa SQLite Database restituita da sqlite_open () quando usato in modo procedurale. Questo parametro non è richiesto nel metodo ad oggetti.

Esempi

Esempio 1. Stile procedurale
<?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); } ?>

Esempio 2. Stile ad oggetti
<?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(); } ?>

Vedere anche:

sqlite_close

(PHP 5)

sqlite_close -- Chiude un database SQLite

Descrizione

void sqlite_close ( resource dbhandle )

Chiude il database indicato dall'handle database. Se il database è persistente, questo sarà chiuso e rimosso dalla lista dei database persistenti.

Elenco dei parametri

dbhandle: Risorsa SQLite Database restituita da sqlite_open () quando usato in modo procedurale.

Esempi

Esempio 1. Esempio di uso di sqlite_close()
<?php $dbhandle = sqlite_open('sqlitedb'); sqlite_close($dbhandle); ?>

Vedere anche:

sqlite_popen()

sqlite_column

(PHP 5)

sqlite_column

(no version information, might be only in CVS)

SQLiteResult->column

(no version information, might be only in CVS)

SQLiteUnbuffered->column -- Scarica una riga dal set di risultati corrente

Descrizione

mixed sqlite_column ( resource result, mixed index_or_name [, bool decode_binary] )

class SQLiteResult {

mixed column ( mixed index_or_name [, bool decode_binary] )

}class SQLiteUnbuffered {

mixed column ( mixed index_or_name [, bool decode_binary] )

}

Scarica il valore dalla colonna index_or_name (se si tratta di una stringa) o della colonna numero index_or_name (se il parametro è un intero) dalla riga corrente del set di risultati indicato da result.

Elenco dei parametri

result: Risorsa SQLite per un set di risultati. Questo parametro non è richiesto quando la funzione è utilizzata nello stile ad oggetti.
index_or_name: Indice o nome della colonna da scaricare.
decode_binary: Quando decode_binary è impostato a TRUE (per default), il PHP decodificherà i dati binari se questi furono codificati con la funzione sqlite_escape_string(). Normalmente si dovrebbe lasciare inalterato il comportamento di default, a meno che non si debba intervenire su database creati da altre applicazioni SQLite.

Note

Nota: Utilizzare questa funzione quando si opera su set di risultati con molte colonne o con colonne che contengano grandi quantità di dati.

Vedere anche:

sqlite_fetch_string()

sqlite_create_aggregate

(PHP 5)

sqlite_create_aggregate

(no version information, might be only in CVS)

SQLiteDatabase->createAggregate -- Registra un aggregato UDF da utilizzare nelle istruzioni SQL

Descrizione

bool sqlite_create_aggregate ( resource dbhandle, string function_name, callback step_func, callback finalize_func [, int num_args] )

Versione ad oggetti (metodo):

class SQLiteDatabase {

bool createAggregate ( string function_name, callback step_func, callback finalize_func [, int num_args] )

}

sqlite_create_aggregate() è simile a sqlite_create_function() tranne che le funzioni di registrazione possono essere utilizzate per calcolare un risultato aggregato da tutte le righe della query.

La differenza chiave tra questa funzione e sqlite_create_function() è che entrambe le funzioni sono necessarie per gestire gli aggregati; la funzione step_func viene richiamata per ogni riga del set di risultati. La funzione PHP personalizzata dovrebbe accumulare i dati memorizzarli nel contesto di aggregazione. Una volta che tutte le righe sono state processate, si esegue la funzione finalize_func che dovrebbe prendere i dati dal contesto di aggregazione e restituire il risultato. La funzione personalizzata deve restituire un tipo riconosciuto da SQLite (ad esempio un tipo scalare).

Elenco dei parametri

dbhandle: Risorsa SQLite Database restituita da sqlite_open () quando usato in modo procedurale. Questo parametro non è richiesto nel metodo ad oggetti.
function_name: Nome della funzione usata nell'istruzione SQL.
step_func: Funzione richiamata per ogni riga del set di risultati.
finalize_func: Funzione di callback richiamata per aggragare i dati da ogni riga.
num_args: Suggerisce al parser SQLite se la funzione di callback accetta un numero predefinito di argomenti.

Esempi

Esempio 1. Esempio di una funzione di aggregazione lunghezza_massima
<?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 questo esempio creiamo una funzione di aggregazione che calcola la lunghezza della stringa più lunga presente in una colonna della tabella. Per ciascuna riga, si esegue la funzione max_len_step nella quale viene passato il parametro context. Questo parametro è come una qualsiasi variabile PHP ed è impostata per contenere un array od un oggetto. In questo esempio, verrà utilizzata semplicemente per contenere la lunghezza massima della stringa; se la string è di lunghezza superiore al valore massimo corrente, noi aggiorneremo il contesto affinchè registri il nuovo massimo.

Quando sono state processate tutte le righe, SQLite esegue la funzione max_len_finalize per determinare il risultato aggregato. In questa funzione possiamo svolgere qualsiasi tipo di operazione basata sui dati presenti nel parametro context. Nel nostro esempio abbiamo calcolato il risultato man mano che si processava la righe, pertanto non ci resta che restituire il valore.

Nota: L'esempio precedente non avrebbe funzionato correttamente se la colonna avesse contenuto dati binari. Guardare sul manuale la pagina sqlite_udf_decode_binary() per una spiegazione del perché, e l'esempio di come questo rispetti la codifica binaria.

Suggerimento: NON si raccomanda si memorizzare nel contesto una copia dei valori di ciascuna riga, per poi processarli alla fina; questo costringe SQLite a utilizzare una grande quantità di memoria per processare la query - basta pensare a quanta memoria sarebbe necessaria se si memorizzasse un milione di righe, ciscuna contenente una stringa di 32 byte.

Suggerimento: Si può utilizzare sqlite_create_function() e sqlite_create_aggregate() per non utilizzare la funzioni SQL native di SQLite.

Vedere anche:

sqlite_udf_encode_binary()

sqlite_udf_decode_binary()

sqlite_create_function

(PHP 5)

sqlite_create_function

(no version information, might be only in CVS)

SQLiteDatabase->createFunction -- Registra una funzione utente "regolare" da utilizzare nelle istruzioni SQL

Descrizione

bool sqlite_create_function ( resource dbhandle, string function_name, callback callback [, int num_args] )

Versione ad oggetti (metodo):

class SQLiteDatabase {

bool createFunction ( string function_name, callback callback [, int num_args] )

}

La funzione sqlite_create_function() permette di registrare una funzione PHP in SQLite come UDF (funzione definita dall'utente, User Defined Function), in modo che possa essere richiamata dalle istruzioni SQL.

Le UDF possono essere utilizzate in qualsiasi istruzione SQL che permetta di richiamare funzioni, tipo SELECT e UPDATE e anche i triggers.

Elenco dei parametri

dbhandle: Risorsa SQLite Database restituita da sqlite_open () quando usato in modo procedurale. Questo parametro non è richiesto nel metodo ad oggetti.
function_name: Indica il nome della funzione che si vuole utilizzare nelle istruzioni SQL.
callback: Funzione di callback richiamata per gestire la funzione SQL.
Nota: Le funzioni di callback devono restituire un tipo noto a SQLite (ad esempio un tipo scalare).
num_args: Indicazione al parser SQLite se la funzione di callback accetta un numero predefinito di argomenti.

Nota: Two alternative syntaxes are supported for compatibility with other database extensions (such as MySQL). The preferred form is the first, where the dbhandle parameter is the first parameter to the function.

Esempi

Esempio 1. Esempio di uso di sqlite_create_function()
<?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 questo esempio abbiamo una funzione che calcola il valore md5 di una stringa e lo inverte. Quando sono eseguite le istruzioni SQL, queste restituiscono il nome del file trasformato dalla nostra funzione. Il valore restituito in $rows contiene il risultato processato.

L'aspetto interessante di questa tecnica è che non è necessario elaborare i dati di una query utilizzando un ciclo foreach() dopo avere eseguito una query per ottenere i dati

Il PHP registra una speciale funzione chiamata php quando apre il database la prima volta. La funzione php può essere utilizzata per chiamare qualsiasi funzione PHP senza doverla registrare prima.

Esempio 2. Esempio dell'uso della funzione php
<?php $rows = sqlite_array_query($dbhandle, "SELECT php('md5', filename) from files"); ?>
Questo esempio chiamerà la funzione md5() per ciasuna colonna filename del database e restituirà il risultato in $rows

Nota: Per motivi di performance, il PHP non convertirà in automatico i dati binari passati da/per la UDF. Occorre convertire manualmente i parametri e restituire i valori nel medesimo modo, se si desidera elaborare i dati binari. Guardare le pagine relative a sqlite_udf_encode_binary() e sqlite_udf_decode_binary() per maggiori dettagli.

Suggerimento: Non è raccomandabile l'uso delle UDF per processare dati binari, a meno che non siano richieste all'applicazione elevate performance.

Suggerimento: Si può utilizzare sqlite_create_function() e sqlite_create_aggregate() per sovrascrivere le funzioni SQL native in SQLite.

Vedere anche:

sqlite_current

(PHP 5)

sqlite_current

(no version information, might be only in CVS)

SQLiteResult->current

(no version information, might be only in CVS)

SQLiteUnbuffered->current -- Scarica la riga corrente di un set di risultati in una matrice

Descrizione

array sqlite_current ( resource result [, int result_type [, bool decode_binary]] )

Versione ad oggetti (metodo):

class SQLiteResult {

array current ( [int result_type [, bool decode_binary]] )

}class SQLiteUnbuffered {

array current ( [int result_type [, bool decode_binary]] )

}

sqlite_current() è simile a sqlite_fetch_array() tranne che non avanza alla riga successiva prima di restituire i dati; la funzione restituisce i dati soltanto dalla posizione corrente.

Elenco dei parametri

result: Risorsa SQLite di un set di risultati. Questo parametro non è necessario quando la funzione è utilizzata ad oggetti.
result_type: The optional result_type parameter accepts a constant and determines how the returned array will be indexed. Using SQLITE_ASSOC will return only associative indices (named fields) while SQLITE_NUM will return only numerical indices (ordinal field numbers). SQLITE_BOTH will return both associative and numerical indices. SQLITE_BOTH is the default for this function.
decode_binary: Quando decode_binary è impostato a TRUE (per default), il PHP decodificherà i dati binari se questi furono codificati con la funzione sqlite_escape_string(). Normalmente si dovrebbe lasciare inalterato il comportamento di default, a meno che non si debba intervenire su database creati da altre applicazioni SQLite.

Valori restituiti

Restituisce una matrice della riga corrente dal set di risultati, oppure FALSE se la posizione corrente è oltre la riga finale.

I nomi delle colonne restituiti da SQLITE_ASSOC e da SQLITE_BOTH saranno maiuscoli o minuscoli in base al valore del parametro di configurazione sqlite.assoc_case.

Vedere anche:

sqlite_seek()

sqlite_error_string

(PHP 5)

sqlite_error_string -- Restituisce la descrizione testuale di un codice di errore

Descrizione

string sqlite_error_string ( int error_code )

Restituisce una descrizione leggibile del error_code restituito dalla funzione sqlite_last_error().

Vedere anche:

sqlite_last_error()

sqlite_escape_string

(PHP 5)

sqlite_escape_string -- Inserisce il carattere di escape in stringa da usarsi in una query

Descrizione

string sqlite_escape_string ( string item )

La funzione sqlite_escape_string() inserisce i caratteri di escape nella stringa indicata da item, per poterla utilizzare nelle istruzioni SQL. Questo processo include il raddoppio dell'apice singolo (') e la verifica della presenza di dati binari non sicuri nella stringa.

Se il parametro item contiene un NUL, oppure comincia con un carattere il cui numero ordinale è 0x01, Il PHP applicherà lo schema di codifica binaria in modo da potere memorizzare e recuperare il dato in binario.

Sebbene la codifica binaria permetta un sicuro inserimento dei dati, questo rende inutilizzabile i semplici confronti di testo e la clausola LIKE sulle colonne che contengono dati binari. In pratica, non dovrebbe essere un problema, se nello schema definito non si prevede l'uso di tali funzioni su colonne binarie (infatti è meglio memorizzati dati binari in altri modi, tipo in file a parte).

Avvertimento

La funzione addslashes() NON dovrebbe essere utilizzata per inserire i caratteri di escape nelle query SQLite; questa porta a strani risultati quando si recuperano i dati.

Nota: Non utilizzare questa funzione per codificare i dati restituiti da funzioni UDF create tramite sqlite_create_function() o sqlite_create_aggregate() - utilizzare invece sqlite_udf_encode_binary().

Vedere anche:

sqlite_udf_encode_binary()

sqlite_exec

(PHP 5)

sqlite_exec

(no version information, might be only in CVS)

SQLiteDatabase->exec -- ESegue una query priva di risultato in un dato database

Descrizione

bool sqlite_exec ( resource dbhandle, string query )

bool sqlite_exec ( string query, resource dbhandle )

Versione ad oggetti (metodo):

class SQLiteDatabase {

bool exec ( string query )

}

Esegue un'espressione SQL, indicata da query sul database (specificato dal parametro dbhandle).

Avvertimento

SQLite esegue molteplici query separate da punto e virgola, in questo modo si può eseguire un batch di istruzioni SQL caricate da un file o racchiuse in uno script.

Elenco dei parametri

query: Query da eseguire.
dbhandle: Risorsa SQLite Database restituita da sqlite_open () quando usato in modo procedurale. Questo parametro non è richiesto nel metodo ad oggetti.

Nota: Two alternative syntaxes are supported for compatibility with other database extensions (such as MySQL). The preferred form is the first, where the dbhandle parameter is the first parameter to the function.

Valori restituiti

Questa funzione restituisce il valore TRUE se ha successo, oppure FALSE per insuccesso. Se si deve eseguire una query che restituisca un risultato eseguire sqlite_query().

I nomi delle colonne restituiti da SQLITE_ASSOC e da SQLITE_BOTH saranno maiuscoli o minuscoli in base al valore del parametro di configurazione sqlite.assoc_case.

Esempi

Esempio 1. Esempio procedurale
<?php $dbhandle = sqlite_open('mysqlitedb'); $query = sqlite_exec($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); } ?>

Esempio 2. Esempio ad oggetti
<?php $dbhandle = new SQLiteDatabase('mysqlitedb'); $query = $dbhandle->exec("UPDATE users SET email='jDoe@example.com' WHERE username='jDoe'"); if (!$query) { exit('Error in query.'); } else { echo 'Number of rows modified: ', $dbhandle->changes(); } ?>

Vedere anche:

sqlite_unbuffered_query()

sqlite_array_query()

sqlite_factory

(PHP 5)

sqlite_factory -- Apre un database SQLite e restituisce un oggetto SQLiteDatabase

Descrizione

SQLiteDatabase sqlite_factory ( string filename [, int mode [, string &error_message]] )

sqlite_factory() si comporta in modo simile a sqlite_open() in quanto apre un database SQLITE o cerca di crearlo se non esiste. Tuttavia, la funzione restituisce un oggetto SQLiteDatabase anzichè una risorsa. Vedere la pagina del manuale di sqlite_open() per maggiori dettagli.

Elenco dei parametri

filename: Il nome del file del database SQLite.
mode: Modalità del file. Intesa per essere utilizzata per aprire il database in modalità sola lettura. Attualmente questo parametro è ignorato dalla libreria SQLite. Il valore di default è il valore ottale 0666 ed è l'impostazione raccomandata.
error_message: Passato per riferimento ed è impostato per restituire un messaggio di errore descrittivo del perchè il database non può essere aperto in caso di errore.

Valori restituiti

Restituisce un oggetto SQLiteDatabase in caso di successo, NULL in caso di errore.

Esempi

Esempio 1. Esempio di uso di sqlite_factory()
<?php $dbhandle = sqlite_factory('sqlitedb'); $dbhandle->query('SELECT user_id, username FROM users'); /* Funzione equivalente a */ $dbhandle = new SQLiteDatabase('sqlitedb'); $dbhandle->query('SELECT user_id, username FROM users'); ?>

Vedere anche:

sqlite_popen()

sqlite_fetch_all

(PHP 5)

sqlite_fetch_all

(no version information, might be only in CVS)

SQLiteResult->fetchAll

(no version information, might be only in CVS)

SQLiteUnbuffered->fetchAll -- Scarica tutte le righe di un risultato in una matrice di matrici

Descrizione

array sqlite_fetch_all ( resource result [, int result_type [, bool decode_binary]] )

Versione ad oggetti (metodo):

class SQLiteResult {

array fetchAll ( [int result_type [, bool decode_binary]] )

}class SQLiteUnbuffered {

array fetchAll ( [int result_type [, bool decode_binary]] )

}

sqlite_fetch_all() restituisce una matrice con l'intero set di risultati dalla risorsa result. E' simile ad eseguire sqlite_query() (oppure sqlite_unbuffered_query()) e quindi sqlite_fetch_array() per ciascuna riga del set di risultati.

Elenco dei parametri

result: Risorsa SQLite. Questo parametro non è richiesto quando si usa il metodo ad oggetti.
result_type: The optional result_type parameter accepts a constant and determines how the returned array will be indexed. Using SQLITE_ASSOC will return only associative indices (named fields) while SQLITE_NUM will return only numerical indices (ordinal field numbers). SQLITE_BOTH will return both associative and numerical indices. SQLITE_BOTH is the default for this function.
decode_binary: Quando decode_binary è impostato a TRUE (per default), il PHP decodificherà i dati binari se questi furono codificati con la funzione sqlite_escape_string(). Normalmente si dovrebbe lasciare inalterato il comportamento di default, a meno che non si debba intervenire su database creati da altre applicazioni SQLite.

Valori restituiti

Restituisce una matrice della riga corrente da un set di risultati, oppure FALSE se la posizione corrente è oltre l'ultima riga.

I nomi delle colonne restituiti da SQLITE_ASSOC e da SQLITE_BOTH saranno maiuscoli o minuscoli in base al valore del parametro di configurazione sqlite.assoc_case.

Esempi

Esempio 1. Esempio procedurale
<?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']; } ?>

Esempio 2. Esempio ad oggetti
<?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']; } ?>

Vedere anche:

sqlite_fetch_array

(PHP 5)

sqlite_fetch_array

(no version information, might be only in CVS)

SQLiteResult->fetch

(no version information, might be only in CVS)

SQLiteUnbuffered->fetch -- Scarica in una matrice la riga successiva da un set di risultati

Descrizione

array sqlite_fetch_array ( resource result [, int result_type [, bool decode_binary]] )

Versione ad oggetti (metodo):

class SQLiteResult {

array fetch ( [int result_type [, bool decode_binary]] )

}class SQLiteUnbuffered {

array fetch ( [int result_type [, bool decode_binary]] )

}

Scarica la riga successiva dal set di risultati indicato da result. Se non vi sono righe successive, restituisce FALSE, altrimenti restituisce una matrice associativa rappresentante i dati della riga.

Elenco dei parametri

result: Risorsa SQLite. Questo parametro non è richiesto nella versione ad oggetti.
result_type: The optional result_type parameter accepts a constant and determines how the returned array will be indexed. Using SQLITE_ASSOC will return only associative indices (named fields) while SQLITE_NUM will return only numerical indices (ordinal field numbers). SQLITE_BOTH will return both associative and numerical indices. SQLITE_BOTH is the default for this function.
decode_binary: Quando decode_binary è impostato a TRUE (per default), il PHP decodificherà i dati binari se questi furono codificati con la funzione sqlite_escape_string(). Normalmente si dovrebbe lasciare inalterato il comportamento di default, a meno che non si debba intervenire su database creati da altre applicazioni SQLite.

Valori restituiti

Restituisce una matrice della riga successiva dal set di risultati, FALSE se la posizine successive è oltre l'ultima riga.

I nomi delle colonne restituiti da SQLITE_ASSOC e da SQLITE_BOTH saranno maiuscoli o minuscoli in base al valore del parametro di configurazione sqlite.assoc_case.

Esempi

Vedere anche:

sqlite_array_query()

sqlite_fetch_string()

sqlite_fetch_column_types

(PHP 5)

sqlite_fetch_column_types

(no version information, might be only in CVS)

SQLiteDatabase->fetchColumnTypes -- Restituisce una matrice con il formato delle colonne di una tabella

Descrizione

array sqlite_fetch_column_types ( string table_name, resource dbhandle [, int result_type] )

Versione ad oggetti (metodo):

class SQLiteDatabase {

array fetchColumnTypes ( string table_name [, int result_type] )

}

sqlite_fetch_column_types() rRestituisce una matrice con il tipo di dato delle colonne della tabella indicata da table_name.

Elenco dei parametri

table_name: Nome della tabella.
dbhandle: Risorsa SQLite Database restituita da sqlite_open () quando usato in modo procedurale. Questo parametro non è richiesto nel metodo ad oggetti.
result_type: The optional result_type parameter accepts a constant and determines how the returned array will be indexed. Using SQLITE_ASSOC will return only associative indices (named fields) while SQLITE_NUM will return only numerical indices (ordinal field numbers). SQLITE_BOTH will return both associative and numerical indices. SQLITE_BOTH is the default for this function.

Valori restituiti

Restituisce una matrice con i tipi di dati delle colonne, oppure FALSE in caso di errore.

I nomi delle colonne restituiti da SQLITE_ASSOC e da SQLITE_BOTH saranno maiuscoli o minuscoli in base al valore del parametro di configurazione sqlite.assoc_case.

Esempi

Esempio 1. Esempio procedurale
<?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"; } ?>

Esempio 2. Esempio ad oggetti
<?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"; } ?>
Il precedente esempio visualizzerà:
Column: bar Type: VARCHAR Column: arf Type: TEXT

sqlite_fetch_object

(PHP 5)

sqlite_fetch_object

(no version information, might be only in CVS)

SQLiteResult->fetchObject

(no version information, might be only in CVS)

SQLiteUnbuffered->fetchObject -- Scarica i dati deti della riga successiva come oggetto

Descrizione

object sqlite_fetch_object ( resource result [, string class_name [, array ctor_params [, bool decode_binary]]] )

Versione ad oggetti (metodo):

class SQLiteResult {

object fetchObject ( [string class_name [, array ctor_params [, bool decode_binary]]] )

}class SQLiteUnbuffered {

object fetchObject ( [string class_name [, array ctor_params [, bool decode_binary]]] )

}

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

sqlite_fetch_single

(PHP 5)

sqlite_fetch_single

(no version information, might be only in CVS)

SQLiteResult->fetchSingle

(no version information, might be only in CVS)

SQLiteUnbuffered->fetchSingle -- Scarica come stringa la prima colonna di un set di risultati

Descrizione

string sqlite_fetch_single ( resource result [, bool decode_binary] )

Versione ad oggetti (metodo):

class SQLiteResult {

string fetchSingle ( [bool decode_binary] )

}class SQLiteUnbuffered {

string fetchSingle ( [bool decode_binary] )

}

sqlite_fetch_single() è simile a sqlite_fetch_array() tranne che restituisce il valore della prima colonna di una riga.

Questo è il mezzo migliore per recuperare i dati quando si è interessati soltanto ai valori di una singola colonna.

Elenco dei parametri

result: SQLite risorsa. Questo parametro non è richiesto quando la funzione viene usata nella versione ad oggetti.
decode_binary: Quando decode_binary è impostato a TRUE (per default), il PHP decodificherà i dati binari se questi furono codificati con la funzione sqlite_escape_string(). Normalmente si dovrebbe lasciare inalterato il comportamento di default, a meno che non si debba intervenire su database creati da altre applicazioni SQLite.

Esempi

Esempio 1. Esempio di uso di sqlite_fetch_single()
<?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); } ?>

Vedere anche:

sqlite_fetch_string

(PHP 5)

sqlite_fetch_string -- Alias di sqlite_fetch_single()

Descrizione

This function is an alias of: sqlite_fetch_single().

sqlite_field_name

(PHP 5)

sqlite_field_name

(no version information, might be only in CVS)

SQLiteResult->fieldName

(no version information, might be only in CVS)

SQLiteUnbuffered->fieldName -- Restituisce il nome di un particolare campo

Descrizione

string sqlite_field_name ( resource result, int field_index )

Versione ad oggetti (metodo):

class SQLiteResult {

string fieldName ( int field_index )

}class SQLiteUnbuffered {

string fieldName ( int field_index )

}

Dato il numero ordinale di colonna, field_index, restituisce il nome del campo dal set di risultati indicato in result.

Elenco dei parametri

result: Risorsa SQLite. Questo parametro non è richiesto quando si utilizza la funzione nella versione ad oggetti.
field_index: Numero ordinale della colonna nel set di risultati.

Valori restituiti

Restituisce il nome del campo dal set di risultati SQLite, dato il numero della colonna, oppure FALSE in caso di errore.

I nomi delle colonne restituiti da SQLITE_ASSOC e da SQLITE_BOTH saranno maiuscoli o minuscoli in base al valore del parametro di configurazione sqlite.assoc_case.

sqlite_has_more

(PHP 5)

sqlite_has_more -- Restituisce se sono disponibili o meno ulteriori righe

Descrizione

bool sqlite_has_more ( resource result )

Indica se sono disponibili o meno ulteriori righe.

Elenco dei parametri

result: Risorsa set di risultati di SQLite.

Valori restituiti

sqlite_has_more() restituisce TRUE se sono disponibili ulteriori righe dal set di risultati result, oppure FALSE in caso contrario.

Vedere anche:

sqlite_has_prev

(PHP 5)

sqlite_has_prev

(no version information, might be only in CVS)

SQLiteResult->hasPrev -- Indica se è disponibile o meno una riga precedente

Descrizione

bool sqlite_has_prev ( resource result )

Object oriented style (method):

class SQLiteResult {

bool hasPrev ( void )

}

Indica se è disponibile o meno una riga precedente nel dato set di risultati.

Elenco dei parametri

result: Risorsa set di risultati di SQLite. Questo parametro non è richiesto nel caso si utilizzi la funzione nella versione ad oggetti.
Nota: This function cannot be used with unbuffered result handles.

Valori restituiti

Restituisce TRUE se vi sono ulteriori righe precedenti dal set di risultati result, oppure FALSE in caso contrario.

Vedere anche:

sqlite_prev()

sqlite_has_more()

sqlite_key

(no version information, might be only in CVS)

sqlite_key

(no version information, might be only in CVS)

SQLiteResult->key -- Restituisce l'indice di riga corrente

Descrizione

int sqlite_key ( resource result )

Object oriented style (method):

class SQLiteResult {

int key ( void )

}

sqlite_key() restituisce l'indice della riga corrente del set di risultati result.

Elenco dei parametri

result: Risorsa set di risultati di SQLite. Questo parametro non è richiesto nel caso si utilizzi la funzione nella versione ad oggetti.
Nota: This function cannot be used with unbuffered result handles.

Valori restituiti

Restituisce l'indice della riga corrente del set di risultati result.

Log delle modifiche

Versione	Descrizione
5.0.4	Prima di PHP 5.0.4, sqlite_key() poteva essere chiamato come metodo dell'oggetto SQLiteResult, e non per via procedurale.

Vedere anche:

sqlite_last_error

(PHP 5)

sqlite_last_error

(no version information, might be only in CVS)

SQLiteDatabase->lastError -- Restituisce il codice di errore dell'ultimo errore accorso sul database

Descrizione

int sqlite_last_error ( resource dbhandle )

Versione ad oggetti (metodo):

class SQLiteDatabase {

int lastError ( void )

}

Restituisce il codice di errore dall'ultima operazione eseguita sul database dbhandle. Una descrizione interpretabile dell'errore può essere ricavata tramite la funzione sqlite_error_string().

Elenco dei parametri

dbhandle: Risorsa SQLite Database restituita da sqlite_open () quando usato in modo procedurale. Questo parametro non è richiesto nel metodo ad oggetti.

Vedere anche:

sqlite_error_string()

sqlite_last_insert_rowid

(PHP 5)

sqlite_last_insert_rowid

(no version information, might be only in CVS)

SQLiteDatabase->lastInsertRowid -- Restituisce l'identificativo di riga dell'ultima riga inserita

Descrizione

int sqlite_last_insert_rowid ( resource dbhandle )

Versione ad oggetti (metodo):

class SQLiteDatabase {

int lastInsertRowid ( void )

}

Restituisce l'identificativo di riga dell'ultima riga inserita nel database dbhandle, se questo è stato creato con un campo auto-increment.

Suggerimento: In SQLite si può creare un campo auto-increment dichiarando questo come INTEGER PRIMARY KEY nello schema della tabella.

Elenco dei parametri

dbhandle: Risorsa SQLite Database restituita da sqlite_open () quando usato in modo procedurale. Questo parametro non è richiesto nel metodo ad oggetti.

sqlite_libencoding

(PHP 5)

sqlite_libencoding -- Restituisce la codifica della libreria SQLite

Descrizione

string sqlite_libencoding ( void )

La libreria SQLite può essere compilata in modalità ISO-8859-1 o UTF-8 compatibile. Questa funzione permette di determinare quale schema di codifica è stato usato per questa versione della libreria.

Avvertimento

Per default il PHP distribuisce libsqlite nella codifica ISO-8859-1. Tuttavia questo non è proprio vero; piuttosto che gestire il formato ISO-8859-1 la libreria opera in modo coerente con le impostazioni locali per quanto riguarda i confronti e gli ordinamenti. Pertanto, più che ISO-8859-1, si dovrebbe pensare come se fosse a 8 bit.

Quando è compilato con il supporto alla codifica UTF-8, SQLite gestisce le codifiche e le decodifiche dei caratteri multi-byte UTF-8, ma non svolge ancora un lavoro completo quando opera sui dati (ad esempio non viene svolta la normalizzazione), e alcune operazioni di confronto possono non essere ancora precise.

Avvertimento

Si raccomanda di non utilizzare il PHP nella configurazione di web-server con le librerie compilate per il supporto di UTF-8, poiché libsqlite abortirà il processo se rileva dei problemi con la codifica UTF-8.

Vedere anche:

sqlite_lib_version()

sqlite_libversion

(PHP 5)

sqlite_libversion -- Restituisce la versione della libreria SQLite

Description

string sqlite_libversion ( void )

Restituisce la versione della libreria SQLite.

Vedere anche:

sqlite_libencoding()

sqlite_next

(PHP 5)

sqlite_next

(no version information, might be only in CVS)

SQLiteResult->next

(no version information, might be only in CVS)

SQLiteUnbuffered->next -- Si sposta al successivo numero di riga

Descrizione

bool sqlite_next ( resource result )

Versione ad oggetti (metodo):

class SQLiteResult {

bool next ( void )

}class SQLiteUnbuffered {

bool next ( void )

}

La funzione sqlite_next() avanza il set di risultati indicato da result alla riga successiva.

Elenco dei parametri

result: Risorsa set di risultati di SQLite. Questo parametro non è richiesto nella versione ad oggetti.

Valori restituiti

Restituisce FALSE se non vi sono ulteriori righe, TRUE in caso contrario.

Vedere anche:

sqlite_seek()

sqlite_num_fields

(PHP 5)

sqlite_num_fields

(no version information, might be only in CVS)

SQLiteResult->numFields

(no version information, might be only in CVS)

SQLiteUnbuffered->numFields -- Resituitsce il numero di campi da un set di risultati

Descrizione

int sqlite_num_fields ( resource result )

Versione ad oggetti (metodo):

class SQLiteResult {

int numFields ( void )

}class SQLiteUnbuffered {

int numFields ( void )

}

Restituisce il numero di campi presenti nel set di risultati result.

Elenco dei parametri

result: Risorsa set di risultati di SQLite. Questo parametro non è richiesto nella versione ad oggetti.

Vedere anche:

sqlite_num_rows

(PHP 5)

sqlite_num_rows

(no version information, might be only in CVS)

SQLiteResult->numRows -- Restituisce il numero di righe da un set di risultati bufferizzato

Description

int sqlite_num_rows ( resource result )

Versione ad oggetti (metodo):

class SQLiteResult {

int numRows ( void )

}

Restituisce il numero di righe dal set di risultati result bufferizzato.

Elenco dei parametri

result: Risorsa set di risultati di SQLite. Questo parametro non è richiesto nella versione ad oggetti.
Nota: This function cannot be used with unbuffered result handles.

Esempi

Esempio 1. Esempio procedurale
<?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"; ?>

Esempio 2. Esempio ad oggetti
<?php $db = new SQLiteDatabase('mysqlitedb'); $result = $db->query("SELECT * FROM mytable WHERE name='John Doe'"); $rows = $result->numRows(); echo "Number of rows: $rows"; ?>

Vedere anche:

sqlite_num_fields()

sqlite_open

(PHP 5)

sqlite_open -- Apre un database SQLite e crea il database se non esiste

Descrizione

resource sqlite_open ( string filename [, int mode [, string &error_message]] )

Versione ad oggetti (costruttore):

class SQLiteDatabase {

__construct ( string filename [, int mode [, string &error_message]] )

}

Apre un database SQLite o lo crea se non esiste.

Elenco dei parametri

filename: Nome del database SQLite. Se il file non esiste, SQLite tenterà di crearlo. Il PHP deve avere i permessi di scrittura sul file se si desidera inserire dei dati o modficare lo schema del database, o creare il database se non esiste.
mode: Specifica la modalità del file. E' inteso per essere utilizzato per l'apertura del file in modalità read-only. Attualmente questo parametro viene ignorato da SQLite. Per default la modalità di apertura è il valore ottale 0666, ed è questa l'impostazione raccomandata.
error_message: Passato per riferimento, è impostato per contenere un messaggio descrittivo di errore nel caso non si riesca ad aprire il database a causa di un errore.

Valori restituiti

Restituisce una risorsa (database handle) se ha successo, oppure FALSE se si verifica un errore.

Esempi

Esempio 1. Esempio di uso di sqlite_open()
<?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); } ?>

Note

Suggerimento: Sui sistemi Unix, SQLite è sensibile agli script che utilizzano la chiamata di sistema fork(). Se si sta utilizzando un tale script, si raccomanda di chiudere la connessione prima dell'esecuzione del fork, e quindi ri-aprirlo nel processo figlio/padre. Per maggiori informazioni su questo particolare vedere L'interfaccia C alla libreria SQLite nella sezione intitolata Multi-Threading e SQLite.

Suggerimento: Si raccomanda di non utilizzare database SQLite su partizioni montate via NFS. Poiché è noto che NFS non è affidabile con i lock, può capitare che si riesca neppure ad aprire il database, o, se ci si riesce, il comportamento dei lock può essere indefinito.

Nota: A partire dalla versione 2.8.2 della libreria SQLite, si può specificare :memory: come valore per il parametro filename in modo da creare database che risiedano soltanto in memoria. Principalmente questo è utile per le elaborazioni temporanee, poiché il database in memoria sarà distrutto non appena il processo termina. Può anche essere utilizzato in coppia con l'istruzione SQL ATTACH DATABASE per caricare altri database in modo da potere muovere i dati tra di loro.

Nota: SQLite sensibile alla modalità sicura e a open_basedir.

Vedere anche:

sqlite_popen()

sqlite_close()

sqlite_factory()

sqlite_popen

(PHP 5)

sqlite_popen -- Apre una connessione persistente ad un database SQLite e crea il database se non esiste

Descrizione

resource sqlite_popen ( string filename [, int mode [, string &error_message]] )

Questa funzione agisce in modo identico a sqlite_open() tranne che utilizza il meccanismo delle risorse persistenti insito in PHP. Per maggiori informazioni sui parametri leggere la pagina del manuale relativa a sqlite_open().

sqlite_popen() per prima cosa verifica se esiste già un connessione persistente per il dato filename. Se ne trova una restituisce quella altrimenti ne apre una nuova.

Il beneficio di questo approccio è che si evita il costo, in termini di performance, di dovere ri-leggere lo schema del database e degli indici ad ogni pagina servita dal server web (qualsiasi SAPI tranne CGI o CLI).

Nota: Se si utilizza la connessione persistente, ed il sottostante database viene aggiornato da un processo che gira in background (ad esempio via crontab), e questo processo ricrea il database riscrivendolo (ad esempio cancellandolo e scrivendone uno nuovo, oppure movendo la nuova versione sulla vecchia), si possono manifestare comportamenti indefiniti quando si torna ad utilizzare la connessione persistente verso il vecchio database.
Per evitare questa situazione, occorre che il processo in background apra lo stesso database ed esegua gli aggiornamenti mediante transazioni.

Elenco dei parametri

filename: Nome del database SQLite. Se il file non esiste, SQLite tenterà di crearlo. Il PHP deve avere i permessi di scrittura sul file se si desidera inserire dei dati o modficare lo schema del database, o creare il database se non esiste.
mode: Specifica la modalità del file. E' inteso per essere utilizzato per l'apertura del file in modalità read-only. Attualmente questo parametro viene ignorato da SQLite. Per default la modalità di apertura è il valore ottale 0666, ed è questa l'impostazione raccomandata.
error_message: Passato per riferimento, è impostato per contenere un messaggio descrittivo di errore nel caso non si riesca ad aprire il database a causa di un errore.

Valori restituiti

Restituisce una risorsa (database handle) se ha successo, oppure FALSE se si verifica un errore.

Vedere anche:

sqlite_close()

sqlite_factory()

sqlite_prev

(PHP 5)

sqlite_prev

(no version information, might be only in CVS)

SQLiteResult->prev -- Si posiziona sulla riga precedente di un set di risultati

Descrizione

bool sqlite_prev ( resource result )

Versione ad oggetti (metodo):

class SQLiteResult {

bool prev ( void )

}

sqlite_prev() si sposta alla riga precedente di result.

Elenco dei parametri

result: Risorsa risultato di SQLite. Questo parametro non è richiesto quando di usa la versione ad oggetti.
Nota: This function cannot be used with unbuffered result handles.

Valori restituiti

La funzione restituisce TRUE se ha successo, oppure FALSE se non esiste un record precedente.

Vedere anche:

sqlite_has_prev()

sqlite_query

(PHP 5)

sqlite_query

(no version information, might be only in CVS)

SQLiteDatabase->query -- Esegue una query su un database e restituisce un puntatore al set di risultati

Descrizione

resource sqlite_query ( resource dbhandle, string query )

resource sqlite_query ( string query, resource dbhandle )

Versione ad oggetti (metodo):

class SQLiteDatabase {

SQLiteResult query ( string query )

}

Esegue le istruzioni SQL indicate in query sul collegamento al database dato.

Elenco dei parametri

query: Query da eseguire.
dbhandle: Risorsa SQLite Database restituita da sqlite_open () quando usato in modo procedurale. Questo parametro non è richiesto nel metodo ad oggetti.

Nota: Two alternative syntaxes are supported for compatibility with other database extensions (such as MySQL). The preferred form is the first, where the dbhandle parameter is the first parameter to the function.

Valori restituiti

Questa funzione restituisce un handle o FALSE se si verifica un errore. Nei casi di query che restituiscano delle righe, l'handle restituito dalla funzione può essere utilizzato nelle funzioni sqlite_fetch_array() e sqlite_seek().

A prescindere dal tipo di query, questa funzione restituisce FALSE se la query fallisce.

sqlite_query() restituisce un puntatore ad un set di risultati bufferizzato e navigabile. Ciò è ragionevole per piccole query dove si ha la necessità di accedere alle righe in ordine casuale. I risultati bufferizzati allocano la memoria necessaria per contenere tutte le righe restituite dalla query, che non saranno restituite fino a che non saranno richieste. Se si ha soltanto la necessità di accedere alle righe in modo sequenziale, si raccomanda l'uso della funzione sqlite_unbuffered_query().

Note

Avvertimento

SQLite esegue molteplici query separate da punto e virgola, pertanto si possono eseguire dei batch SQL che possono essere caricati da file esterni o inseriti nello script. Tuttavia ciò è valido solo quando non è utilizzato il risultato della funzione, se, al contrario, viene utilizzato, verrà eseguito solo la prima query. Funzioni tipo sqlite_exec() eseguono sempre molteplici query SQL.

Quando si eseguono query molteplici, il valore restituito può essere FALSE se vi è un errore, oppure indefinito in caso contrario ( può essere TRUE oppure può restituire un handle ad un set di risultati).

Vedere anche:

sqlite_unbuffered_query()

sqlite_array_query()

sqlite_rewind

(PHP 5)

sqlite_rewind

(no version information, might be only in CVS)

SQLiteResult->rewind -- Si posiziona sulla prima riga

Descrizione

bool sqlite_rewind ( resource result )

Versione ad oggetti (metodo):

class SQLiteResult {

bool rewind ( void )

}

sqlite_rewind() si posiziona sulla prima riga del set di risultati.

Elenco dei parametri

result: Risorsa risultato di SQLite. Questo parametro non è richiesto nella versione ad oggetti.
Nota: This function cannot be used with unbuffered result handles.

Valori restituiti

La funzione restituisce FALSE se non vi sono righe nel set di risultati, TRUE in caso contrario.

Vedere anche:

sqlite_seek()

sqlite_seek

(PHP 5)

sqlite_seek

(no version information, might be only in CVS)

SQLiteResult->seek -- Posizionamento su una data riga di un set di risultati bufferizzato

Descrizione

bool sqlite_seek ( resource result, int rownum )

Versione ad oggetti (metodo):

class SQLiteResult {

bool seek ( int rownum )

}

sqlite_seek() si posiziona sulla riga indicata dal parametro rownum.

Elenco dei parametri

result: Risorsa risultato di SQLite. Questo parametro non è richiesto nella versione ad oggetti.
Nota: This function cannot be used with unbuffered result handles.
rownum: Il numero ordinale di riga da cercare. I numeri di riga partono da zero ( 0 indica la prima riga).
Nota: This function cannot be used with unbuffered result handles.

Valori restituiti

La funzione restituisce FALSE se la riga richiesta non esiste, oppure TRUE.

Vedere anche:

sqlite_single_query

(PHP 5)

sqlite_single_query

(no version information, might be only in CVS)

SQLiteDatabase->singleQuery -- Esegue una query e restituisce o una matrice per ogni singola colonna o il valore della prima riga

Descrizione

mixed sqlite_single_query ( resource db, string query [, bool first_row_only [, bool decode_binary]] )

Versione ad oggetti (metodo):

class SQLiteDatabase {

mixed singleQuery ( string query [, bool first_row_only [, bool decode_binary]] )

}

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

sqlite_udf_decode_binary

(PHP 5)

sqlite_udf_decode_binary -- Decodifica dati binari passati come parametri in UDF

Descrizione

string sqlite_udf_decode_binary ( string data )

La funzione sqlite_udf_decode_binary() decodifica i dati binari in modo che possano essere utilizzati come parametri per sqlite_udf_encode_binary() o sqlite_escape_string().

Occorre eseguire questa funzione sui parametri passati agli UDF se questi devono gestire dati binari, poiché la codifica dei dati binari utilizzata dal PHP nasconde il contenuto.

Il PHP non esegue questa codifica/decodifica in automatico, avrebbe impatti negativi sulle performance.

Esempi

Esempio 1. Esempio di una funzione di aggregazione lunghezza_massima binary-safe
<?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')); ?>

Vedere anche:

sqlite_udf_encode_binary()

sqlite_udf_encode_binary

(PHP 5)

sqlite_udf_encode_binary -- Codifica i dati binari prima di restituirli da un UDF

Descrizione

string sqlite_udf_encode_binary ( string data )

sqlite_udf_encode_binary() applica la decofica dei dati binari al parametro data in modo che possa essere restituito dalle query (dato che la sottostante libreria libsqlite API non è binary safe).

Se esiste una possibilità che i dati possano essere binai (ad esempio contengono caratteri tipo NUL, oppure iniziano con il carattere 0x01), occorre eseguire questa funzione per codificare il valore da restituire all'UDF.

Il PHP non esegue questa codifica/decodifica in automatico, avrebbe impatti negativi sulle performance.

Nota: Non utilizzare sqlite_escape_string() per quitare stringhe restituite tramite UDF poiché porta ad avere una quotazione doppia. Utilizzare sqlite_udf_encode_binary()!

Vedere anche:

sqlite_udf_decode_binary()

sqlite_escape_string()

sqlite_unbuffered_query

(PHP 5)

sqlite_unbuffered_query

(no version information, might be only in CVS)

SQLiteDatabase->unbufferedQuery -- Esegue una query senza scaricare e bufferizzare i dati

Descrizione

resource sqlite_unbuffered_query ( resource dbhandle, string query )

resource sqlite_unbuffered_query ( string query, resource dbhandle )

Versione ad oggetti (metodo):

class SQLiteDatabase {

SQLiteUnbuffered unbufferedQuery ( string query )

}

sqlite_unbuffered_query() è simile a sqlite_query() tranne che i risultati sono restituiti in modo sequenziale una riga dopo l'altra, permettendo solo la lettura del record successivo.

Questa funzione è l'ideale per generare oggetti tipo tavole HTML in cui occorre processare una riga alla volta e non occorre muoversi a caso tra le righe.

Nota: Funzioni tipo sqlite_seek(), sqlite_rewind(), sqlite_next(), sqlite_current(), e sqlite_num_rows() non sono applicabili agli handles restituiti da sqlite_unbuffered_query().

Elenco dei parametri

query: La query da eseguire.
dbhandle: Risorsa SQLite Database restituita da sqlite_open () quando usato in modo procedurale. Questo parametro non è richiesto nel metodo ad oggetti.

Nota: Two alternative syntaxes are supported for compatibility with other database extensions (such as MySQL). The preferred form is the first, where the dbhandle parameter is the first parameter to the function.

Valori restituiti

Resituisce un puntatore ad un risultato oppure FALSE.

sqlite_unbuffered_query() restituisce un set di risultati sequenzialeche può essere utilizzato per leggere una riga dopo l'altra.

Vedere anche:

sqlite_valid

(PHP 5)

sqlite_valid

(no version information, might be only in CVS)

SQLiteResult->valid

(no version information, might be only in CVS)

SQLiteUnbuffered->valid -- Indica se una o più righe sono disponibili

Descrizione

bool sqlite_valid ( resource result )

Versione ad oggetti (metodo):

class SQLiteResult {

bool valid ( void )

}class SQLiteUnbuffered {

bool valid ( void )

}

Verifica se una o più righe sono disponibili nel dato set di risultati.

Elenco dei parametri

result: Risorsa risultato di SQLite. Questo parametro non è richiesto quando la funzione viene usata ad oggetti.
Nota: This function cannot be used with unbuffered result handles.

Valori restituiti

Restituisce TRUE se vi sono più righe disponibili da result, oppure FALSE in caso contrario.

Vedere anche:

CXLII. SQLite Functions (PDO_SQLITE)

Introduzione

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.

Sommario
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

PDO_SQLITE DSN

(no version information, might be only in CVS)

PDO_SQLITE DSN -- Connecting to SQLite databases

Descrizione

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.

Nota: The sqlite2 driver is only available in PHP 5.1 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.

Esempi

Esempio 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

(no version information, might be only in CVS)

PDO::sqliteCreateAggregate -- Registers an aggregating User Defined Function for use in SQL statements

Descrizione

bool PDO::sqliteCreateAggregate ( string function_name, callback step_func, callback finalize_func [, int num_args] )

Avvertimento

PDO::sqliteCreateAggregate() 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 function and PDO::sqliteCreateFunction() 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).

Elenco dei parametri

function_name: The name of the function used in SQL statements.
step_func: Callback function called for each row of the result set.
finalize_func: Callback function to aggregate the "stepped" data from each row.
num_args: Hint to the SQLite parser if the callback function accepts a predetermined number of arguments.

Esempi

Esempio 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, $string) { if (strlen($string) > $context) { $context = strlen($string); } } function max_len_finalize(&$context) { 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.

Suggerimento: 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.

Suggerimento: You can use PDO::sqliteCreateFunction() and PDO::sqliteCreateAggregate() to override SQLite native SQL functions.

Nota: This method is not available with the SQLite2 driver. Use the old style sqlite API for that instead.

Vedere anche:

PDO::sqliteCreateFunction()

PDO::sqliteCreateFunction

(no version information, might be only in CVS)

PDO::sqliteCreateFunction -- Registers a User Defined Function for use in SQL statements

Descrizione

bool PDO::sqliteCreateFunction ( string function_name, callback callback [, int num_args] )

Avvertimento

PDO::sqliteCreateFunction() 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.

Elenco dei parametri

function_name: The name of the function used in SQL statements.
callback: Callback function to handle the defined SQL function.
Nota: 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.

Nota: Two alternative syntaxes are supported for compatibility with other database extensions (such as MySQL). The preferred form is the first, where the dbhandle parameter is the first parameter to the function.

Esempi

Esempio 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.

Suggerimento: You can use PDO::sqliteCreateFunction() and PDO::sqliteCreateAggregate() to override SQLite native SQL functions.

Nota: This method is not available with the SQLite2 driver. Use the old style sqlite API for that instead.

Vedere anche:

PDO::sqliteCreateAggregate()

Reference Counting and Aliasing (by Andi Gutmans)

CXLIII. Secure Shell2 Functions

Introduzione

Bindings to the libssh2 library which provide access to resources (shell, remote exec, tunneling, file transfer) on a remote machine using a secure cryptographic transport.

Installazione

Windows binaries may be found at http://snaps.php.net/. To install, download php_ssh2.dll to the folder specified by your php.ini file's extension_dir directive. Enable it by adding extension=php_ssh2.dll to your php.ini and restarting your webserver.

extension_dir=c:/php5/exts/
extension=php_ssh2.dll

Linux, BSD, and other *nix variants can be compiled using the following steps:

Download and install OpenSSL. If you install OpenSSL via your distribution's packaging system be sure to install the development libraries as well. This will typically be a package named openssl-dev, openssl_devel, or some variation thereof.
Download and install libssh2. Typically this means executing the following command from the libssh2 source tree. ./configure && make all install.
Run the pear installer for PECL/ssh2: pear install ssh2
Copy ssh2.so from the directory indicated by the build process to the location specified in your php.ini file under extension_dir.
Add extension=ssh2.so to your php.ini
Restart your webserver to reload your php.ini settings.

Development Versions: There are currently no stable versions of PECL/ssh2, to force installation of the beta version of PECL/ssh2 execute: pear install ssh2-beta

Compiling PECL/ssh2 without using the PEAR command: Rather than using pear install ssh2 to automatically download and install PECL/ssh2, you may download the tarball from PECL. From the root of the unpacked tarball, run: phpize && ./configure --with-ssh2 && make to generate ssh2.so. Once built, continue the installation from step 4 above.

Additional information such as new releases, downloads, source files, maintainer information, and a CHANGELOG, can be located here: http://pecl.php.net/package/ssh2.

Nota: You will need version 0.4 or greater of the libssh2 library (possibly higher, see release notes).

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

SSH2_FINGERPRINT_MD5 (integer): Flag to ssh2_fingerprint() requesting hostkey fingerprint as an MD5 hash.
SSH2_FINGERPRINT_SHA1 (integer): Flag to ssh2_fingerprint() requesting hostkey fingerprint as an SHA1 hash.
SSH2_FINGERPRINT_HEX (integer): Flag to ssh2_fingerprint() requesting hostkey fingerprint as a string of hexits.
SSH2_FINGERPRINT_RAW (integer): Flag to ssh2_fingerprint() requesting hostkey fingerprint as a raw string of 8-bit characters.
SSH2_TERM_UNIT_CHARS (integer): Flag to ssh2_shell() specifying that width and height are provided as character sizes.
SSH2_TERM_UNIT_PIXELS (integer): Flag to ssh2_shell() specifying that width and height are provided in pixel units.
SSH2_DEFAULT_TERM_WIDTH (integer): Default terminal width requested by ssh2_shell().
SSH2_DEFAULT_TERM_HEIGHT (integer): Default terminal height requested by ssh2_shell().
SSH2_DEFAULT_TERM_UNIT (integer): Default terminal units requested by ssh2_shell().
SSH2_STREAM_STDIO (integer): Flag to ssh2_fetch_stream() requesting STDIO subchannel.
SSH2_STREAM_STDERR (integer): Flag to ssh2_fetch_stream() requesting STDERR subchannel.
SSH2_DEFAULT_TERMINAL (string): Default terminal type (e.g. vt102, ansi, xterm, vanilla) requested by ssh2_shell().

Sommario
ssh2_auth_hostbased_file -- Authenticate using a public hostkey
ssh2_auth_none -- Authenticate as "none"
ssh2_auth_password -- Authenticate over SSH using a plain password
ssh2_auth_pubkey_file -- Authenticate using a public key
ssh2_connect -- Connect to an SSH server
ssh2_exec -- Execute a command on a remote server
ssh2_fetch_stream -- Fetch an extended data stream
ssh2_fingerprint -- Retreive fingerprint of remote server
ssh2_methods_negotiated -- Return list of negotiated methods
ssh2_publickey_add -- Add an authorized publickey
ssh2_publickey_init -- Initialize Publickey subsystem
ssh2_publickey_list -- List currently authorized publickeys
ssh2_publickey_remove -- Remove an authorized publickey
ssh2_scp_recv -- Request a file via SCP
ssh2_scp_send -- Send a file via SCP
ssh2_sftp_lstat -- Stat a symbolic link
ssh2_sftp_mkdir -- Create a directory
ssh2_sftp_readlink -- Return the target of a symbolic link
ssh2_sftp_realpath -- Resolve the realpath of a provided path string
ssh2_sftp_rename -- Rename a remote file
ssh2_sftp_rmdir -- Remove a directory
ssh2_sftp_stat -- Stat a file on a remote filesystem
ssh2_sftp_symlink -- Create a symlink
ssh2_sftp_unlink -- Delete a file
ssh2_sftp -- Initialize SFTP subsystem
ssh2_shell -- Request an interactive shell
ssh2_tunnel -- Open a tunnel through a remote server

ssh2_auth_hostbased_file

(PECL)

ssh2_auth_hostbased_file -- Authenticate using a public hostkey

Description

bool ssh2_auth_hostbased_file ( resource session, string username, string hostname, string pubkeyfile, string privkeyfile [, string passphrase [, string local_username]] )

Authenticate using a public hostkey read from a file. If privkeyfile is encrypted (which it should be), the passphrase must be provided. If local_username is omitted, then the value for username will be used for it.

Esempio 1. Authentication using a public hostkey

<?php
$connection = ssh2_connect('shell.example.com', 22, array('hostkey'=>'ssh-rsa'));

if (ssh2_auth_hostbased_file($connection, 'remoteusername', 'myhost.example.com',
                             '/usr/local/etc/hostkey_rsa.pub',
                             '/usr/local/etc/hostkey_rsa', 'secret',
                             'localusername')) {
  echo "Public Key Hostbased Authentication Successful\n";
} else {
  die('Public Key Hostbased Authentication Failed');
}
?>

Nota: ssh2_auth_hostbased_file() requires libssh2 >= 0.7 and PHP/SSH2 >= 0.7

ssh2_auth_none

(PECL)

ssh2_auth_none -- Authenticate as "none"

Description

mixed ssh2_auth_none ( resource session, string username )

Attempt "none" authentication which usually will (and should) fail. As part of the failure, this function will return an array of accepted authentication methods. If the server does accept "none" as an authentication method for username, this function will simply return TRUE.

Esempio 1. Using ssh2_auth_none() to retreive a list of authentication methods.

<?php
$connection = ssh2_connect('shell.example.com', 22);

$auth_methods = ssh2_auth_none($connection, 'user');

if (in_array('password', $auth_methods)) {
  echo "Server supports password based authentication\n";
}
?>

ssh2_auth_password

(PECL)

ssh2_auth_password -- Authenticate over SSH using a plain password

Description

bool ssh2_auth_password ( resource session, string username, string password )

Authenticate over SSH using a plain password

Esempio 1. Authenticating with a password

<?php
$connection = ssh2_connect('shell.example.com', 22);

if (ssh2_auth_password($connection, 'username', 'secret')) {
  echo "Authentication Successful!\n";
} else {
  die('Authentication Failed...');
}
?>

ssh2_auth_pubkey_file

(PECL)

ssh2_auth_pubkey_file -- Authenticate using a public key

Description

bool ssh2_auth_pubkey_file ( resource session, string username, string pubkeyfile, string privkeyfile [, string passphrase] )

Authenticate using a public key read from a file. If privkeyfile is encrypted (which it should be), the passphrase must be provided.

Esempio 1. Authentication using a public key

<?php
$connection = ssh2_connect('shell.example.com', 22, array('hostkey'=>'ssh-rsa'));

if (ssh2_auth_pubkey_file($connection, 'username',
                          '/home/username/.ssh/id_rsa.pub',
                          '/home/username/.ssh/id_rsa', 'secret')) {
  echo "Public Key Authentication Successful\n";
} else {
  die('Public Key Authentication Failed');
}
?>

ssh2_connect

(PECL)

ssh2_connect -- Connect to an SSH server

Description

resource ssh2_connect ( string host [, int port [, array methods [, array callbacks]]] )

Establish a connection to a remote SSH server and return a resource on success, FALSE on error.

methods may be an associative array with up to four parameters as described below.

Tabella 1. methods may be an associative array with any or all of the following parameters.

Index	Meaning	Supported Values*
kex	List of key exchange methods to advertise, comma separated in order of preference.	`diffie-hellman-group1-sha1`, `diffie-hellman-group14-sha1`, and `diffie-hellman-group-exchange-sha1`
hostkey	List of hostkey methods to advertise, come separated in order of preference.	`ssh-rsa` and `ssh-dss`
client_to_server	Associative array containing crypt, compression, and message authentication code (MAC) method preferences for messages sent from client to server.
server_to_client	Associative array containing crypt, compression, and message authentication code (MAC) method preferences for messages sent from client to server.

* - Supported Values are dependent on methods supported by underlying library. See libssh2 documentation for additional information.

Tabella 2. client_to_server and server_to_client may be an associative array with any or all of the following parameters.

Index	Meaning	Supported Values*
crypt	List of crypto methods to advertise, comma separated in order of preference.	`rijndael-cbc@lysator.liu.se`, `aes256-cbc`, `aes192-cbc`, `aes128-cbc`, `3des-cbc`, `blowfish-cbc`, `cast128-cbc`, `arcfour`, and `none**`
comp	List of compression methods to advertise, comma separated in order of preference.	`zlib` and `none`
mac	List of MAC methods to advertise, come separated in order of preference.	`hmac-sha1`, `hmac-sha1-96`, `hmac-ripemd160`, `hmac-ripemd160@openssh.com`, and `none**`

Crypt and MAC method "none": For security reasons, none is disabled by the underlying libssh2 library unless explicitly enabled during build time by using the appropriate ./configure options. See documentation for the underlying library for more information.

Tabella 3. callbackss may be an associative array with any or all of the following parameters.

Index	Meaning	Prototype
ignore	Name of function to call when an `SSH2_MSG_IGNORE` packet is received	void ignore_cb($message)
debug	Name of function to call when an `SSH2_MSG_DEBUG` packet is received	void debug_cb($message, $language, $always_display)
macerror	Name of function to call when a packet is received but the message authentication code failed. If the callback returns `TRUE`, the mismatch will be ignored, otherwise the connection will be terminated.	bool macerror_cb($packet)
disconnect	Name of function to call when an `SSH2_MSG_DISCONNECT` packet is received	void disconnect_cb($reason, $message, $language)

Esempio 1. Open a connection forcing 3des-cbc when sending packets, any strength aes cipher when receiving packets, no compression in either direction, and Group1 key exchange.

<?php
/* Notify the user if the server terminates the connection */
function my_ssh_disconnect($reason, $message, $language) {
  printf("Server disconnected with reason code [%d] and message: %s\n",
         $reason, $message);
}

$methods = array(
  'kex' => 'diffie-hellman-group1-sha1',
  'client_to_server' => array(
    'crypt' => '3des-cbc',
    'comp' => 'none'),
  'server_to_client' => array(
    'crypt' => 'aes256-cbc,aes192-cbc,aes128-cbc',
    'comp' => 'none'));

$callbacks = array('disconnect' => 'my_ssh_disconnect');

$connection = ssh2_connect('shell.example.com', 22, $methods, $callbacks);
if (!$connection) die('Connection failed');
?>

Esempio 1. Checking the fingerprint against a known value

<?php
$known_host = '6F89C2F0A719B30CC38ABDF90755F2E4';

$connection = ssh2_connect('shell.example.com', 22);

$fingerprint = ssh2_fingerprint($connection,
               SSH2_FINGERPRINT_MD5 | SSH2_FINGERPRINT_HEX);

if ($fingerprint != $known_host) {
  die("HOSTKEY MISMATCH!\n" .
      "Possible Man-In-The-Middle Attack?");
}
?>

ssh2_methods_negotiated

(PECL)

ssh2_methods_negotiated -- Return list of negotiated methods

Description

array ssh2_methods_negotiated ( resource session )

Returns list of negotiated methods.

Esempio 1. Determining what methods were negotiated

<?php
$connection = ssh2_connect('shell.example.com', 22);
$methods = ssh2_methods_negotiated($connection);

echo "Encryption keys were negotiated using: {$methods['kex']}\n";
echo "Server identified using an {$methods['hostkey']} with ";
echo "fingerprint: " . ssh2_fingerprint($connection) . "\n";

echo "Client to Server packets will use methods:\n";
echo "\tCrypt: {$methods['client_to_server']['crypt']}\n";
echo "\tComp: {$methods['client_to_server']['comp']}\n";
echo "\tMAC: {$methods['client_to_server']['mac']}\n";

echo "Server to Client packets will use methods:\n";
echo "\tCrypt: {$methods['server_to_client']['crypt']}\n";
echo "\tComp: {$methods['server_to_client']['comp']}\n";
echo "\tMAC: {$methods['server_to_client']['mac']}\n";

?>

ssh2_publickey_add

(PECL)

ssh2_publickey_add -- Add an authorized publickey

Descrizione

bool ssh2_publickey_add ( resource pkey, string algoname, string blob [, bool overwrite [, array attributes]] )

Nota: The publickey subsystem is used for managing publickeys on a server to which the client is already authenticated. To authenticate to a remote system using publickey authentication, use the ssh2_auth_pubkey_file() function instead.

Elenco dei parametri

pkey: Publickey Subsystem resource created by ssh2_publickey_init().
algoname: Publickey algorithm (e.g.): ssh-dss, ssh-rsa
blob: Publickey blob as raw binary data
overwrite: If the specified key already exists, should it be overwritten?
attributes: Associative array of attributes to assign to this public key. Refer to ietf-secsh-publickey-subsystem for a list of supported attributes. To mark an attribute as mandatory, preceed its name with an asterix. If the server is unable to support an attribute marked mandatory, it will abort the add process.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 1. Adding a publickey with ssh2_publickey_add()
<?php $ssh2 = ssh2_connect('shell.example.com', 22); ssh2_auth_password($ssh2, 'jdoe', 'password'); $pkey = ssh2_publickey_init($ssh2); $keyblob = base64_decode(' AAAAB3NzaC1yc2EAAAABIwAAAIEA5HVt6VqSGd5PTrLRdjNONxXH1tVFGn0 Bd26BF0aCP9qyJRlvdJ3j4WBeX4ZmrveGrjMgkseSYc4xZ26sDHwfL351xj zaLpipu\BGRrw17mWVBhuCExo476ri5tQFzbTc54VEHYckxQ16CjSTibI5X 69GmnYC9PNqEYq/1TP+HF10='); ssh2_publickey_add($ssh2, 'ssh-rsa', $keyblob, false, array('comment'=>"John's Key")); ?>

Vedere anche:

ssh2_publickey_init()

ssh2_publickey_remove()

ssh2_publickey_list()

ssh2_publickey_init

(PECL)

ssh2_publickey_init -- Initialize Publickey subsystem

Descrizione

resource ssh2_publickey_init ( resource session )

Request the Publickey subsystem from an already connected SSH2 server.

The publickey subsystem allows an already connected and authenticated client to manage the list of authorized public keys stored on the target server in an implementation agnostic manner. If the remote server does not support the publickey subsystem, the ssh2_publickey_init() function will return FALSE.

Nota: The publickey subsystem is used for managing publickeys on a server to which the client is already authenticated. To authenticate to a remote system using publickey authentication, use the ssh2_auth_pubkey_file() function instead.

Valori restituiti

Returns an SSH2 Publickey Subsystem resource for use with all other ssh2_publickey_*() methods.

Vedere anche:

ssh2_publickey_add()

ssh2_publickey_remove()

ssh2_publickey_list()

ssh2_publickey_list

(PECL)

ssh2_publickey_list -- List currently authorized publickeys

Descrizione

array ssh2_publickey_list ( resource pkey )

Nota: The publickey subsystem is used for managing publickeys on a server to which the client is already authenticated. To authenticate to a remote system using publickey authentication, use the ssh2_auth_pubkey_file() function instead.

Elenco dei parametri

pkey: Publickey Subsystem resource

Valori restituiti

Returns a numericly indexed array of keys, each of which is an associative array containing: name, blob, and attrs elements.

Tabella 1. Publickey elements

Array Key	Meaning
name	Name of algorithm used by this publickey, for example: `ssh-dss` or `ssh-rsa`.
blob	Publickey blob as raw binary data.
attrs	Attributes assigned to this publickey. The most common attribute, and the only one supported by publickey version 1 servers, is `comment`, which may be any freeform string.

Esempi

Esempio 1. Listing authorized keys with ssh2_publickey_list()
<?php $ssh2 = ssh2_connect('shell.example.com', 22); ssh2_auth_password($ssh2, 'jdoe', 'secret'); $pkey = ssh2_publickey_init($ssh2); $list = ssh2_publickey_list($pkey); foreach($list as $key) { echo "Key: {$key['name']}\n"; echo "Blob: " . chunk_split(base64_encode($key['blob']), 40, "\n") . "\n"; echo "Comment: {$key['attrs']['comment']}\n\n"; } ?>
Il precedente esempio visualizzerà:
Key: ssh-rsa Blob: AAAAB3NzaC1yc2EAAAABIwAAAIEA5HVt6VqSGd5P TrLRdjNONxXH1tVFGn0Bd26BF0aCP9qyJRlvdJ3j 4WBeX4ZmrveGrjMgkseSYc4xZ26sDHwfL351xjza Lpipu\BGRrw17mWVBhuCExo476ri5tQFzbTc54VE HYckxQ16CjSTibI5X69GmnYC9PNqEYq/1TP+HF10 Comment: John's Key Key: ssh-rsa Blob: AAAAB3NzaHVt6VqSGd5C1yc2EAAAABIwA232dnJA AIEA5HVt6VqSGd5PTrLRdjNONxX/1TP+HF1HVt6V qSGd50H1tVFGn0BB3NzaC1yc2EAd26BF0aCP9qyJ RlvdJ3j4WBeX4ZmrveGrjMgkseSYc4xZ26HVt6Vq SGd5sDHwfL351xjzaLpipu\BGB3NzaC1yc2EA/1T Comment: Alice's Key

Vedere anche:

ssh2_publickey_init()

ssh2_publickey_add()

ssh2_publickey_remove()

ssh2_publickey_remove

(PECL)

ssh2_publickey_remove -- Remove an authorized publickey

Descrizione

bool ssh2_publickey_remove ( resource pkey, string algoname, string blob )

Nota: The publickey subsystem is used for managing publickeys on a server to which the client is already authenticated. To authenticate to a remote system using publickey authentication, use the ssh2_auth_pubkey_file() function instead.

Elenco dei parametri

pkey: Publickey Subsystem Resource
algoname: Publickey algorithm (e.g.): ssh-dss, ssh-rsa
blob: Publickey blob as raw binary data

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

Esempio 1. Resolving a pathname

<?php
$connection = ssh2_connect('shell.example.com', 22);
ssh2_auth_password($connection, 'username', 'password');
$sftp = ssh2_sftp($connection);

$realpath = ssh2_sftp_realpath($sftp, '/home/username/../../../..//./usr/../etc/passwd');
/* $realpath is now: '/etc/passwd' */
?>

ssh2_sftp_rename

(PECL)

ssh2_sftp_rename -- Rename a remote file

Description

bool ssh2_sftp_rename ( resource sftp, string from, string to )

Renames a file on the remote filesystem.

Esempio 1. Renaming a file via sftp

<?php
$connection = ssh2_connect('shell.example.com', 22);
ssh2_auth_password($connection, 'username', 'password');
$sftp = ssh2_sftp($connection);

ssh2_sftp_rename($sftp, '/home/username/oldname', '/home/username/newname');
?>

ssh2_sftp_rmdir

(PECL)

ssh2_sftp_rmdir -- Remove a directory

Description

bool ssh2_sftp_rmdir ( resource sftp, string dirname )

Removes a directory from the remote file server. This function is similar to using rmdir() with the ssh2.sftp:// wrapper.

Esempio 1. Removing a directory on a remote server

<?php
$connection = ssh2_connet('shell.example.com', 22);
ssh2_auth_password($connection, 'username', 'password');
$sftp = ssh2_sftp($connection);

ssh2_sftp_rmdir($sftp, '/home/username/deltodel');
/* Or:  rmdir("ssh2.sftp://$sftp/home/username/dirtodel"); */
?>

See Also: rmdir(), and ssh2_sftp_mkdir()

ssh2_sftp_stat

(PECL)

ssh2_sftp_stat -- Stat a file on a remote filesystem

Description

array ssh2_sftp_stat ( resource sftp, string path )

Stats a file on the remote filesystem following any symbolic links. This function is similar to using the stat() function with the ssh2.sftp:// wrapper in PHP5 and returns the same values. See the documentation for stat() for details on the values which may be returned.

Esempio 1. Stating a file via SFTP

<?php
$connection = ssh2_connect('shell.example.com', 22);
ssh2_auth_password($connection, 'username', 'password');

$sftp = ssh2_sftp($connection);
$statinfo = ssh2_stat($sftp, '/path/to/symlink');

$filesize = $statinfo['size'];
$group = $statinfo['gid'];
$owner = $statinfo['uid'];
$atime = $statinfo['atime'];
$mtime = $statinfo['mtime'];
$mode = $statinfo['mode'];
?>

ssh2_sftp_symlink

(PECL)

ssh2_sftp_symlink -- Create a symlink

Description

bool ssh2_sftp_symlink ( resource sftp, string target, string link )

Creates a symbolic link named link on the remote filesystem pointing to target.

Esempio 1. Creating a symbolic link

<?php
$connection = ssh2_connect('shell.example.com', 22);
ssh2_auth_password($connection, 'username', 'password');
$sftp = ssh2_sftp($connection);

ssh2_sftp_symlink($sftp, '/var/run/mysql.sock', '/tmp/mysql.sock');
?>

See Also: symlink(), and ssh2_sftp_readlink()

ssh2_sftp_unlink

(PECL)

ssh2_sftp_unlink -- Delete a file

Description

bool ssh2_sftp_unlink ( resource sftp, string filename )

Deletes a file on the remote filesystem

Esempio 1. Deleting a file

<?php
$connection = ssh2_connect('shell.example.com', 22);
ssh2_auth_password($connection, 'username', 'password');
$sftp = ssh2_sftp($connection);

ssh2_sftp_unlink($sftp, '/home/username/stale_file');
?>

ssh2_sftp

(PECL)

ssh2_sftp -- Initialize SFTP subsystem

Description

resource ssh2_sftp ( resource session )

Request the SFTP subsystem from an already connected SSH2 server.

This method returns an SSH2 SFTP resource for use with all other ssh2_sftp_*() methods and the ssh2.sftp:// fopen wrapper.

Esempio 1. Opening a file via SFTP

<?php
$connection = ssh2_connect('shell.example.com', 22);
ssh2_auth_password($connection, 'username', 'password');

$sftp = ssh2_sftp($connection);

$stream = fopen("ssh2.sftp://$sftp/path/to/file", 'r');
?>

ssh2_shell

(PECL)

ssh2_shell -- Request an interactive shell

Description

resource ssh2_shell ( resource session [, string term_type [, array env [, int width [, int height [, int width_height_type]]]]] )

Open a shell at the remote end and allocate a stream for it. term_type should correspond to one of the entries in the target system's /etc/termcap file and defaults to vanilla. env may be passed as an associative array of name/value pairs to set in the target environment.

width, and height define the width and height of the virtual terminal allocated for the shell process. width_height_type should be one of SSH2_TERM_UNIT_CHARS or SSH2_TERM_UNIT_PIXELS.

Esempio 1. Executing a command

<?php
$connection = ssh2_connect('shell.example.com', 22);
ssh2_auth_password($connection, 'username', 'password');

$stream = ssh2_shell($connection, 'vt102', null, 80, 24, SSH2_TERM_UNIT_CHARS);
?>

ssh2_tunnel

(PECL)

ssh2_tunnel -- Open a tunnel through a remote server

Description

resource ssh2_tunnel ( resource session, string host, int port )

Open a socket stream to an arbitrary host/port by way of the currently connected SSH server.

Esempio 1. Opening a tunnel to an arbitrary host

<?php
$connection = ssh2_connect('shell.example.com', 22);
ssh2_auth_pubkey_file($connection, 'username', 'id_dsa.pub', 'id_dsa');

$tunnel = ssh2_tunnel($connection, '10.0.0.101', 12345);
?>

See Also: ssh2_connect(), and fsockopen()

CXLIV. Stream Functions

Introduzione

Streams were introduced with PHP 4.3.0 as a way of generalizing file, network, data compression, and other operations which share a common set of functions and uses. In its simplest definition, a stream is a resource object which exhibits streamable behavior. That is, it can be read from or written to in a linear fashion, and may be able to fseek() to an arbitrary locations within the stream.

A wrapper is additional code which tells the stream how to handle specific protocols/encodings. For example, the http wrapper knows how to translate a URL into an HTTP/1.0 request for a file on a remote server. There are many wrappers built into PHP by default (See Appendice M), and additional, custom wrappers may be added either within a PHP script using stream_wrapper_register(), or directly from an extension using the API Reference in Capitolo 44. Because any variety of wrapper may be added to PHP, there is no set limit on what can be done with them. To access the list of currently registered wrappers, use stream_get_wrappers().

A stream is referenced as: scheme://target

scheme(string) - The name of the wrapper to be used. Examples include: file, http, https, ftp, ftps, compress.zlib, compress.bz2, and php. See Appendice M for a list of PHP builtin wrappers. If no wrapper is specified, the function default is used (typically file://).
target - Depends on the wrapper used. For filesystem related streams this is typically a path and filename of the desired file. For network related streams this is typically a hostname, often with a path appended. Again, see Appendice M for a description of targets for builtin streams.

Stream Filters

A filter is a final piece of code which may perform operations on data as it is being read from or written to a stream. Any number of filters may be stacked onto a stream. Custom filters can be defined in a PHP script using stream_filter_register() or in an extension using the API Reference in Capitolo 44. To access the list of currently registered filters, use stream_get_filters().

Stream Contexts

A context is a set of parameters and wrapper specific options which modify or enhance the behavior of a stream. Contexts are created using stream_context_create() and can be passed to most filesystem related stream creation functions (i.e. fopen(), file(), file_get_contents(), etc...).

Options can be specified when calling stream_context_create(), or later using stream_context_set_option(). A list of wrapper specific options can be found with the list of built-in wrappers (See Appendice M).

In addition, parameters may be set on a context using stream_context_set_params(). Currently the only context parameter supported by PHP is notification. The value of this parameter must be the name of a function to be called when an event occurs on a stream. The notification function called during an event should accept the following six parameters:

void my_notifier ( int notification_code, int severity, string message, int message_code, int bytes_transferred, int bytes_max )

notification_code and severity are numerical values which correspond to the STREAM_NOTIFY_* constants listed below. If a descriptive message is available from the stream, message and message_code will be populated with the appropriate values. The meaning of these values is dependent on the specific wrapper in use. bytes_transferred and bytes_max will be populated when applicable.

Installazione

Streams are an integral part of PHP as of version 4.3.0. No steps are required to enable them.

Stream Classes

User designed wrappers can be registered via stream_wrapper_register(), using the class definition shown on that manual page.

class php_user_filter is predefined and is an abstract baseclass for use with user defined filters. See the manual page for stream_filter_register() for details on implementing user defined filters.

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

Constant	Description
`STREAM_FILTER_READ` *	Used with stream_filter_append() and stream_filter_prepend() to indicate that the specified filter should only be applied when reading
`STREAM_FILTER_WRITE` *	Used with stream_filter_append() and stream_filter_prepend() to indicate that the specified filter should only be applied when writing
`STREAM_FILTER_ALL` *	This constant is equivalent to `STREAM_FILTER_READ \| STREAM_FILTER_WRITE`
`PSFS_PASS_ON` *	`Return Code` indicating that the userspace filter returned buckets in `$out`.
`PSFS_FEED_ME` *	`Return Code` indicating that the userspace filter did not return buckets in `$out` (i.e. No data available).
`PSFS_ERR_FATAL` *	`Return Code` indicating that the userspace filter encountered an unrecoverable error (i.e. Invalid data received).
`STREAM_USE_PATH`	`Flag` indicating if the `stream` used the include path.
`STREAM_REPORT_ERRORS`	`Flag` indicating if the `wrapper` is responsible for raising errors using trigger_error() during opening of the stream. If this flag is not set, you should not raise any errors.
`STREAM_CLIENT_ASYNC_CONNECT` *	Open client socket asynchronously. This option must be used together with the `STREAM_CLIENT_CONNECT` flag. Used with stream_socket_client().
`STREAM_CLIENT_CONNECT` *	Open client socket connection. Client sockets should always include this flag. Used with stream_socket_client().
`STREAM_CLIENT_PERSISTENT` *	Client socket opened with stream_socket_client() should remain persistent between page loads.
`STREAM_SERVER_BIND` *	Tells a stream created with stream_socket_server() to bind to the specified target. Server sockets should always include this flag.
`STREAM_SERVER_LISTEN` *	Tells a stream created with stream_socket_server() and bound using the `STREAM_SERVER_BIND` flag to start listening on the socket. Connection-orientated transports (such as TCP) must use this flag, otherwise the server socket will not be enabled. Using this flag for connect-less transports (such as UDP) is an error.
`STREAM_NOTIFY_RESOLVE` *	A remote address required for this stream has been resolved, or the resolution failed. See `severity` for an indication of which happened.
`STREAM_NOTIFY_CONNECT`	A connection with an external resource has been established.
`STREAM_NOTIFY_AUTH_REQUIRED`	Additional authorization is required to access the specified resource. Typical issued with `severity` level of `STREAM_NOTIFY_SEVERITY_ERR`.
`STREAM_NOTIFY_MIME_TYPE_IS`	The `mime-type` of resource has been identified, refer to `message` for a description of the discovered type.
`STREAM_NOTIFY_FILE_SIZE_IS`	The `size` of the resource has been discovered.
`STREAM_NOTIFY_REDIRECTED`	The external resource has redirected the stream to an alternate location. Refer to `message`.
`STREAM_NOTIFY_PROGRESS`	Indicates current progress of the stream transfer in `bytes_transferred` and possibly `bytes_max` as well.
`STREAM_NOTIFY_COMPLETED` *	There is no more data available on the stream.
`STREAM_NOTIFY_FAILURE`	A generic error occurred on the stream, consult `message` and `message_code` for details.
`STREAM_NOTIFY_AUTH_RESULT`	Authorization has been completed (with or without success).
`STREAM_NOTIFY_SEVERITY_INFO`	Normal, non-error related, notification.
`STREAM_NOTIFY_SEVERITY_WARN`	Non critical error condition. Processing may continue.
`STREAM_NOTIFY_SEVERITY_ERR`	A critical error occurred. Processing cannot continue.
`STREAM_IPPROTO_ICMP` +	Provides a ICMP socket.
`STREAM_IPPROTO_IP` +	Provides a IP socket.
`STREAM_IPPROTO_RAW` +	Provides a RAW socket.
`STREAM_IPPROTO_TCP` +	Provides a TCP socket.
`STREAM_IPPROTO_UDP` +	Provides a UDP socket.
`STREAM_PF_INET` +	Internet Protocol Version 4 (IPv4).
`STREAM_PF_INET6` +	Internet Protocol Version 6 (IPv6).
`STREAM_PF_UNIX` +	Unix system internal protocols.
`STREAM_SOCK_DGRAM` +	Provides datagrams, which are connectionless messages (UDP, for example).
`STREAM_SOCK_RAW` +	Provides a raw socket, which provides access to internal network protocols and interfaces. Usually this type of socket is just available to the root user.
`STREAM_SOCK_RDM` +	Provides a RDM (Reliably-delivered messages) socket.
`STREAM_SOCK_SEQPACKET` +	Provides a sequenced packet stream socket.
`STREAM_SOCK_STREAM` +	Provides sequenced, two-way byte streams with a transmission mechanism for out-of-band data (TCP, for example).

Nota: The constants marked with * are just available since PHP 5.0.0.

Nota: The constants marked with + are available since PHP 5.1.0 and are meant to be used with stream_socket_pair(). Please note that some of these constants might not be available in your system.

Stream Errors

As with any file or socket related function, an operation on a stream may fail for a variety of normal reasons (i.e.: Unable to connect to remote host, file not found, etc...). A stream related call may also fail because the desired stream is not registered on the running system. See the array returned by stream_get_wrappers() for a list of streams supported by your installation of PHP. As with most PHP internal functions if a failure occurs an E_WARNING message will be generated describing the nature of the error.

Esempi

Esempio 1. Using file_get_contents() to retrieve data from multiple sources
<?php /* Read local file from /home/bar */ $localfile = file_get_contents("/home/bar/foo.txt"); /* Identical to above, explicitly naming FILE scheme */ $localfile = file_get_contents("file:///home/bar/foo.txt"); /* Read remote file from www.example.com using HTTP */ $httpfile = file_get_contents("http://www.example.com/foo.txt"); /* Read remote file from www.example.com using HTTPS */ $httpsfile = file_get_contents("https://www.example.com/foo.txt"); /* Read remote file from ftp.example.com using FTP */ $ftpfile = file_get_contents("ftp://user:pass@ftp.example.com/foo.txt"); /* Read remote file from ftp.example.com using FTPS */ $ftpsfile = file_get_contents("ftps://user:pass@ftp.example.com/foo.txt"); ?>

Esempio 2. Making a POST request to an https server
<?php /* Send POST request to https://secure.example.com/form_action.php * Include form elements named "foo" and "bar" with dummy values */ $sock = fsockopen("ssl://secure.example.com", 443, $errno, $errstr, 30); if (!$sock) die("$errstr ($errno)\n"); $data = "foo=" . urlencode("Value for Foo") . "&bar=" . urlencode("Value for Bar"); fwrite($sock, "POST /form_action.php HTTP/1.0\r\n"); fwrite($sock, "Host: secure.example.com\r\n"); fwrite($sock, "Content-type: application/x-www-form-urlencoded\r\n"); fwrite($sock, "Content-length: " . strlen($data) . "\r\n"); fwrite($sock, "Accept: */*\r\n"); fwrite($sock, "\r\n"); fwrite($sock, "$data\r\n"); fwrite($sock, "\r\n"); $headers = ""; while ($str = trim(fgets($sock, 4096))) $headers .= "$str\n"; echo "\n"; $body = ""; while (!feof($sock)) $body .= fgets($sock, 4096); fclose($sock); ?>

Esempio 3. Writing data to a compressed file
<?php /* Create a compressed file containing an arbitrarty string * File can be read back using compress.zlib stream or just * decompressed from the command line using 'gzip -d foo-bar.txt.gz' */ $fp = fopen("compress.zlib://foo-bar.txt.gz", "wb"); if (!$fp) die("Unable to create file."); fwrite($fp, "This is a test.\n"); fclose($fp); ?>

Sommario
stream_bucket_append -- Append bucket to brigade
stream_bucket_make_writeable -- Return a bucket object from the brigade for operating on
stream_bucket_new -- Create a new bucket for use on the current stream
stream_bucket_prepend -- Prepend bucket to brigade
stream_context_create -- Create a streams context
stream_context_get_default -- Retreive the default streams context
stream_context_get_options -- Retrieve options for a stream/wrapper/context
stream_context_set_option -- Sets an option for a stream/wrapper/context
stream_context_set_params -- Set parameters for a stream/wrapper/context
stream_copy_to_stream -- Copies data from one stream to another
stream_filter_append -- Attach a filter to a stream
stream_filter_prepend -- Attach a filter to a stream
stream_filter_register -- Register a stream filter implemented as a PHP class derived from php_user_filter
stream_filter_remove -- Remove a filter from a stream
stream_get_contents -- Reads remainder of a stream into a string
stream_get_filters -- Retrieve list of registered filters
stream_get_line -- Gets line from stream resource up to a given delimiter
stream_get_meta_data -- Retrieves header/meta data from streams/file pointers
stream_get_transports -- Retrieve list of registered socket transports
stream_get_wrappers -- Retrieve list of registered streams
stream_register_wrapper -- Alias of stream_wrapper_register()
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
stream_set_timeout -- Set timeout period on a stream
stream_set_write_buffer -- Sets file buffering on the given stream
stream_socket_accept -- Accept a connection on a socket created by stream_socket_server()
stream_socket_client -- Open Internet or Unix domain socket connection
stream_socket_enable_crypto -- Turns encryption on/off on an already connected socket
stream_socket_get_name -- Retrieve the name of the local or remote sockets
stream_socket_pair -- Creates a pair of connected, indistinguishable socket streams
stream_socket_recvfrom -- Receives data from a socket, connected or not
stream_socket_sendto -- Sends a message to a socket, whether it is connected or not
stream_socket_server -- Create an Internet or Unix domain server socket
stream_wrapper_register -- Register a URL wrapper implemented as a PHP class
stream_wrapper_restore -- Restores a previously unregistered built-in wrapper
stream_wrapper_unregister -- Unregister a URL wrapper

Esempio 1. Using stream_context_create()

<?php
$opts = array(
  'http'=>array(
    'method'=>"GET",
    'header'=>"Accept-language: en\r\n" . 
              "Cookie: foo=bar\r\n"
  )
);

$context = stream_context_create($opts);

/* Sends an http request to www.example.com
   with additional headers shown above */
$fp = fopen('http://www.example.com', 'r', false, $context);
fpassthru($fp);
fclose($fp);
?>

See also stream_context_set_option(), and Listing of supported wrappers with context options (Appendice M).

stream_context_get_default

(PHP 5 >= 5.1.0RC1)

stream_context_get_default -- Retreive the default streams context

Description

resource stream_context_get_default ( [array options] )

Returns the default stream context which is used whenever file operations (fopen(), file_get_contents(), etc...) are called without a context parameter. Options for the default context can optionally be specified with this function using the same syntax as stream_context_create().

options must be an associative array of associative arrays in the format $arr['wrapper']['option'] = $value.

Esempio 1. Using stream_context_get_default()

<?php
$default_opts = array(
  'http'=>array(
    'method'=>"GET",
    'header'=>"Accept-language: en\r\n" . 
              "Cookie: foo=bar",
    'proxy'=>"tcp://10.54.1.39:8000"
  )
);


$alternate_opts = array(
  'http'=>array(
    'method'=>"POST",
    'header'=>"Content-type: application/x-www-form-urlencoded\r\n" .
              "Content-length: " . strlen("baz=bomb"),
    'content'=>"baz=bomb"
  )
);

$default = stream_context_get_default($default_opts);
$alternate = stream_context_create($alternate_opts);

/* Sends a regular GET request to proxy server at 10.54.1.39
 * For www.example.com using context options specified in $default_opts
 */
readfile('http://www.example.com');

/* Sends a POST request directly to www.example.com
 * Using context options specified in $alternate_opts
 */
readfile('http://www.example.com', false, $alternate);

?>

params should be an associative array of the structure: $params['paramname'] = "paramvalue";.

Tabella 1. Parameters

Parameters	Purpose
`notification`	Name of user-defined callback function to be called whenever a stream triggers a notification.

stream_copy_to_stream

(PHP 5)

stream_copy_to_stream -- Copies data from one stream to another

Descrizione

int stream_copy_to_stream ( resource source, resource dest [, int maxlength [, int offset]] )

Makes a copy of up to maxlength bytes of data from the current position (or from the offset position, if specified) in source to dest. If maxlength is not specified, all remaining content in source will be copied.

Elenco dei parametri

source: The source stream
dest: The destination stream
maxlength: Maximum bytes to copy
offset: The offset where to start to copy data

Valori restituiti

Returns the total count of bytes copied.

Log delle modifiche

Versione	Descrizione
5.1.0	Added the `offset` parameter

Esempi

Esempio 1. A stream_copy_to_stream() example
<?php $src = fopen('http://www.example.com', 'r'); $dest1 = fopen('first1k.txt', 'w'); $dest2 = fopen('remainder.txt', 'w'); echo stream_copy_to_stream($src, $dest1, 1024) . " bytes copied to first1k.txt\n"; echo stream_copy_to_stream($src, $dest2) . " bytes copied to remainder.txt\n"; ?>

Vedere anche:

copy()

stream_filter_append

(PHP 4 >= 4.3.0, PHP 5)

stream_filter_append -- Attach a filter to a stream

Description

resource stream_filter_append ( resource stream, string filtername [, int read_write [, mixed params]] )

Adds filtername to the list of filters attached to stream. This filter will be added with the specified params to the end of the list and will therefore be called last during stream operations. To add a filter to the beginning of the list, use stream_filter_prepend().

By default, stream_filter_append() will attach the filter to the read filter chain if the file was opened for reading (i.e. File Mode: r, and/or +). The filter will also be attached to the write filter chain if the file was opened for writing (i.e. File Mode: w, a, and/or +). STREAM_FILTER_READ, STREAM_FILTER_WRITE, and/or STREAM_FILTER_ALL can also be passed to the read_write parameter to override this behavior.

As of PHP 5.1.0, this function returns a resource which can be used to refer to this filter instance during a call to stream_filter_remove(). Prior to PHP 5.1.0, this function returns TRUE on success or FALSE on failure.

Esempio 1. Controlling where filters are applied
<?php /* Open a test file for reading and writing */ $fp = fopen("test.txt", "rw"); /* Apply the ROT13 filter to the * write filter chain, but not the * read filter chain */ stream_filter_append($fp, "string.rot13", STREAM_FILTER_WRITE); /* Write a simple string to the file * it will be ROT13 transformed on the * way out */ fwrite($fp, "This is a test\n"); /* Back up to the beginning of the file */ rewind($fp); /* Read the contents of the file back out. * Had the filter been applied to the * read filter chain as well, we would see * the text ROT13ed back to its original state */ fpassthru($fp); fclose($fp); /* Expected Output --------------- Guvf vf n grfg */ ?>

When using custom (user) filters: stream_filter_register() must be called first in order to register the desired user filter to filtername.

Nota: Stream data is read from resources (both local and remote) in chunks, with any unconsumed data kept in internal buffers. When a new filter is appended to a stream, data in the internal buffers is processed through the new filter at that time. This differs from the behavior of stream_filter_prepend().

stream_filter_prepend

(PHP 4 >= 4.3.0, PHP 5)

stream_filter_prepend -- Attach a filter to a stream

Description

resource stream_filter_prepend ( resource stream, string filtername [, int read_write [, mixed params]] )

Adds filtername to the list of filters attached to stream. This filter will be added with the specified params to the beginning of the list and will therefore be called first during stream operations. To add a filter to the end of the list, use stream_filter_append().

By default, stream_filter_prepend() will attach the filter to the read filter chain if the file was opened for reading (i.e. File Mode: r, and/or +). The filter will also be attached to the write filter chain if the file was opened for writing (i.e. File Mode: w, a, and/or +). STREAM_FILTER_READ, STREAM_FILTER_WRITE, and/or STREAM_FILTER_ALL can also be passed to the read_write parameter to override this behavior. See stream_filter_append() for an example of using this parameter.

When using custom (user) filters: stream_filter_register() must be called first in order to register the desired user filter to filtername.

Nota: Stream data is read from resources (both local and remote) in chunks, with any unconsumed data kept in internal buffers. When a new filter is prepended to a stream, data in the internal buffers, which has already been processed through other filters will not be reprocessed through the new filter at that time. This differs from the behavior of stream_filter_append().

stream_filter_register

(PHP 5)

stream_filter_register -- Register a stream filter implemented as a PHP class derived from php_user_filter

Description

bool stream_filter_register ( string filtername, string classname )

stream_filter_register() allows you to implement your own filter on any registered stream used with all the other filesystem functions (such as fopen(), fread() etc.).

To implement a filter, you need to define a class as an extension of php_user_filter with a number of member functions as defined below. When performing read/write operations on the stream to which your filter is attached, PHP will pass the data through your filter (and any other filters attached to that stream) so that the data may be modified as desired. You must implement the methods exactly as described below - doing otherwise will lead to undefined behaviour.

stream_filter_register() will return FALSE if the filtername is already defined.

int filter ( resource in, resource out, int &consumed, bool closing )

This method is called whenever data is read from or written to the attached stream (such as with fread() or fwrite()). in is a resource pointing to a bucket brigade which contains one or more bucket objects containing data to be filtered. out is a resource pointing to a second bucket brigade into which your modified buckets should be placed. consumed, which must always be declared by reference, should be incremented by the length of the data which your filter reads in and alters. In most cases this means you will increment consumed by $bucket->datalen for each $bucket. If the stream is in the process of closing (and therefore this is the last pass through the filterchain), the closing parameter will be set to TRUE The filter method must return one of three values upon completion.

Return Value	Meaning
`PSFS_PASS_ON`	Filter processed successfully with data available in the `out` `bucket brigade`.
`PSFS_FEED_ME`	Filter processed successfully, however no data was available to return. More data is required from the stream or prior filter.
`PSFS_ERR_FATAL` (default)	The filter experienced an unrecoverable error and cannot continue.

bool onCreate ( void )

This method is called during instantiation of the filter class object. If your filter allocates or initializes any other resources (such as a buffer), this is the place to do it. Your implementation of this method should return FALSE on failure, or TRUE on success.

When your filter is first instantiated, and yourfilter->onCreate() is called, a number of properties will be available as shown in the table below.

Property	Contents
`FilterClass->filtername`	A string containing the name the filter was instantiated with. Filters may be registered under multiple names or under wildcards. Use this property to determine which name was used.
`FilterClass->params`	The contents of the `params` parameter passed to stream_filter_append() or stream_filter_prepend().

void onClose ( void )

This method is called upon filter shutdown (typically, this is also during stream shutdown), and is executed after the flush method is called. If any resources were allocated or initialzed during onCreate this would be the time to destroy or dispose of them.

The example below implements a filter named strtoupper on the foo-bar.txt stream which will capitalize all letter characters written to/read from that stream.
Esempio 1. Filter for capitalizing characters on foo-bar.txt stream
<?php /* Define our filter class */ class strtoupper_filter extends php_user_filter { function filter($in, $out, &$consumed, $closing) { while ($bucket = stream_bucket_make_writeable($in)) { $bucket->data = strtoupper($bucket->data); $consumed += $bucket->datalen; stream_bucket_append($out, $bucket); } return PSFS_PASS_ON; } } /* Register our filter with PHP */ stream_filter_register("strtoupper", "strtoupper_filter") or die("Failed to register filter"); $fp = fopen("foo-bar.txt", "w"); /* Attach the registered filter to the stream just opened */ stream_filter_append($fp, "strtoupper"); fwrite($fp, "Line1\n"); fwrite($fp, "Word - 2\n"); fwrite($fp, "Easy As 123\n"); fclose($fp); /* Read the contents back out */ readfile("foo-bar.txt"); ?>
Il precedente esempio visualizzerà:
LINE1 WORD - 2 EASY AS 123

Esempio 2. Registering a generic filter class to match multiple filter names.
<?php /* Define our filter class */ class string_filter extends php_user_filter { var $mode; function filter($in, $out, &$consumed, $closing) { while ($bucket = stream_bucket_make_writeable($in)) { if ($this->mode == 1) { $bucket->data = strtoupper($bucket->data); } elseif ($this->mode == 0) { $bucket->data = strtolower($bucket->data); } $consumed += $bucket->datalen; stream_bucket_append($out, $bucket); } return PSFS_PASS_ON; } function onCreate() { if ($this->filtername == 'str.toupper') { $this->mode = 1; } elseif ($this->filtername == 'str.tolower') { $this->mode = 0; } else { /* Some other str.* filter was asked for, report failure so that PHP will keep looking */ return false; } return true; } } /* Register our filter with PHP */ stream_filter_register("str.*", "string_filter") or die("Failed to register filter"); $fp = fopen("foo-bar.txt", "w"); /* Attach the registered filter to the stream just opened We could alternately bind to str.tolower here */ stream_filter_append($fp, "str.toupper"); fwrite($fp, "Line1\n"); fwrite($fp, "Word - 2\n"); fwrite($fp, "Easy As 123\n"); fclose($fp); /* Read the contents back out */ readfile("foo-bar.txt"); ?>
Il precedente esempio visualizzerà:
LINE1 WORD - 2 EASY AS 123

stream_filter_remove

(PHP 5 >= 5.1.0RC1)

stream_filter_remove -- Remove a filter from a stream

Description

bool stream_filter_remove ( resource stream_filter )

Removes a stream filter previously added to a stream with stream_filter_prepend() or stream_filter_append(). Any data remaining in the filter's internal buffer will be flushed through to the next filter before removing it.

Esempio 1. Dynamicly refiltering a stream
<?php /* Open a test file for reading and writing */ $fp = fopen("test.txt", "rw"); $rot13_filter = stream_filter_append($fp, "string.rot13", STREAM_FILTER_WRITE); fwrite($fp, "This is "); stream_filter_remove($rot13_filter); fwrite($fp, "a test\n"); rewind($fp); fpassthru($fp); fclose($fp); /* Expected Output --------------- Guvf vf a test */ ?>

stream_get_contents

(PHP 5)

stream_get_contents -- Reads remainder of a stream into a string

Description

string stream_get_contents ( resource handle [, int maxlength [, int offset]] )

Identical to file_get_contents(), except that stream_get_contents() operates on an already open stream resource and returns the remaining contents in a string, up to maxlength bytes and starting at the specified offset.

Elenco dei parametri

handle (resource): A stream resource (e.g. returned from fopen())
maxlength (integer): The maximum bytes to read. Defaults to -1 (read all the remaining buffer).
offset (integer): Seek to the specified offset before reading. Added in PHP 5.1.0.

Valori restituiti

Returns a string, or FALSE on failure.

Esempi

Esempio 1. stream_get_contents() example
<?php if ($stream = fopen('http://www.example.com', 'r')) { // print all the page starting at the offset 10 echo stream_get_contents($stream, -1, 10); fclose($stream); } if ($stream = fopen('http://www.example.net', 'r')) { // print the first 5 bytes echo stream_get_contents($stream, 5); fclose($stream); } ?>

Vedere anche:

fgets()

fread()

fpassthru()

Nota: Questa funzione è binary-safe (gestisce correttamente i file binari)

stream_get_filters

(PHP 5)

stream_get_filters -- Retrieve list of registered filters

Description

array stream_get_filters ( void )

Returns an indexed array containing the name of all stream filters available on the running system.

Esempio 1. Using stream_get_filters()
<?php $streamlist = stream_get_filters(); print_r($streamlist); ?>
Output will be similar to the following. Note: there may be more or fewer filters in your version of PHP.
Array ( [0] => string.rot13 [1] => string.toupper [2] => string.tolower [3] => string.base64 [4] => string.quoted-printable )

stream_get_line

(PHP 5)

stream_get_line -- Gets line from stream resource up to a given delimiter

Description

string stream_get_line ( resource handle, int length [, string ending] )

Returns a string of up to length bytes read from the file pointed to by handle. Reading ends when length bytes have been read, when the string specified by ending is found (which is not included in the return value), or on EOF (whichever comes first).

If an error occurs, returns FALSE.

This function is nearly identical to fgets() except in that it allows end of line delimiters other than the standard \n, \r, and \r\n, and does not return the delimiter itself.

See also fread(), fgets(), and fgetc().

stream_get_meta_data

(PHP 4 >= 4.3.0, PHP 5)

stream_get_meta_data -- Retrieves header/meta data from streams/file pointers

Description

array stream_get_meta_data ( resource stream )

Returns information about an existing stream. The stream can be any stream created by fopen(), fsockopen() and pfsockopen(). The result array contains the following items:

timed_out (bool) - TRUE if the stream timed out while waiting for data on the last call to fread() or fgets().
blocked (bool) - TRUE if the stream is in blocking IO mode. See stream_set_blocking().
eof (bool) - TRUE if the stream has reached end-of-file. Note that for socket streams this member can be TRUE even when unread_bytes is non-zero. To determine if there is more data to be read, use feof() instead of reading this item.
unread_bytes (int) - the number of bytes currently contained in the PHP's own internal buffer.
Nota: You shouldn't use this value in a script.

The following items were added in PHP 4.3:

stream_type (string) - a label describing the underlying implementation of the stream.
wrapper_type (string) - a label describing the protocol wrapper implementation layered over the stream. See Appendice M for more information about wrappers.
wrapper_data (mixed) - wrapper specific data attached to this stream. See Appendice M for more information about wrappers and their wrapper data.
filters (array) - and array containing the names of any filters that have been stacked onto this stream. Documentation on filters can be found in the Filters appendix.

Nota: This function was introduced in PHP 4.3, but prior to this version, socket_get_status() could be used to retrieve the first four items, for socket based streams only.
In PHP 4.3 and later, socket_get_status() is an alias for this function.

Nota: This function does NOT work on sockets created by the Socket extension.

The following items were added in PHP 5.0:

mode (string) - the type of access required for this stream (see Table 1 of the fopen() reference)
seekable (bool) - whether the current stream can be seeked.
uri (string) - the URI/filename associated with this stream.

stream_get_transports

(PHP 5)

stream_get_transports -- Retrieve list of registered socket transports

Description

array stream_get_transports ( void )

Nota: When stream_select() returns, the arrays read, write and except are modified to indicate which stream resource(s) actually changed status.

The tv_sec and tv_usec together form the timeout parameter, tv_sec specifies the number of seconds while tv_usec the number of microseconds. The timeout is an upper bound on the amount of time that stream_select() will wait before it returns. If tv_sec and tv_usec are both set to 0, stream_select() will not wait for data - instead it will return immediately, indicating the current status of the streams. If tv_sec is NULL stream_select() can block indefinitely, returning only when an event on one of the watched streams occurs (or if a signal interrupts the system call).

On success stream_select() returns the number of stream resources contained in the modified arrays, which may be zero if the timeout expires before anything interesting happens. On error FALSE is returned and a warning raised (this can happen if the system call is interrupted by an incoming signal).

Avvertimento

Using a timeout value of 0 allows you to instantaneously poll the status of the streams, however, it is NOT a good idea to use a 0 timeout value in a loop as it will cause your script to consume too much CPU time.

It is much better to specify a timeout value of a few seconds, although if you need to be checking and running other code concurrently, using a timeout value of at least 200000 microseconds will help reduce the CPU usage of your script.

Remember that the timeout value is the maximum time that will elapse; stream_select() will return as soon as the requested streams are ready for use.

You do not need to pass every array to stream_select(). You can leave it out and use an empty array or NULL instead. Also do not forget that those arrays are passed by reference and will be modified after stream_select() returns.

This example checks to see if data has arrived for reading on either $stream1 or $stream2. Since the timeout value is 0 it will return immediately:
<?php /* Prepare the read array */ $read = array($stream1, $stream2); if (false === ($num_changed_streams = stream_select($read, $write = NULL, $except = NULL, 0))) { /* Error handling */ } elseif ($num_changed_streams > 0) { /* At least on one of the streams something interesting happened */ } ?>

Nota: Due to a limitation in the current Zend Engine it is not possible to pass a constant modifier like NULL directly as a parameter to a function which expects this parameter to be passed by reference. Instead use a temporary variable or an expression with the leftmost member being a temporary variable:
<?php
stream_select($r, $w, $e = NULL, 0);
?>

Nota: Be sure to use the === operator when checking for an error. Since the stream_select() may return 0 the comparison with == would evaluate to TRUE:
<?php
if (false === stream_select($r, $w, $e = NULL, 0)) {
    echo "stream_select() failed\n";
}
?>

Nota: If you read/write to a stream returned in the arrays be aware that they do not necessarily read/write the full amount of data you have requested. Be prepared to even only be able to read/write a single byte.

Nota: Windows compatibility: stream_select() used on a pipe returned from proc_open() may cause data loss under Windows 98.
Use of stream_select() on file descriptors returned by proc_open() will fail and return FALSE under Windows.

stream_set_blocking

(PHP 4 >= 4.3.0, PHP 5)

stream_set_blocking -- Set blocking/non-blocking mode on a stream

Description

bool stream_set_blocking ( resource stream, int mode )

If mode is 0, the given stream will be switched to non-blocking mode, and if 1, it will be switched to blocking mode. This affects calls like fgets() and fread() that read from the stream. In non-blocking mode an fgets() call will always return right away while in blocking mode it will wait for data to become available on the stream.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

This function was previously called as set_socket_blocking() and later socket_set_blocking() but this usage is deprecated.

Nota: Prior to PHP 4.3, this function only worked on socket based streams. Since PHP 4.3, this function works for any stream that supports non-blocking mode (currently, regular files and socket streams).

stream_set_timeout

(PHP 4 >= 4.3.0, PHP 5)

stream_set_timeout -- Set timeout period on a stream

Description

bool stream_set_timeout ( resource stream, int seconds [, int microseconds] )

Sets the timeout value on stream, expressed in the sum of seconds and microseconds. Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

When the stream times out, the 'timed_out' key of the array returned by stream_get_meta_data() is set to TRUE, although no error/warning is generated.

Esempio 1. stream_set_timeout() example
<?php $fp = fsockopen("www.example.com", 80); if (!$fp) { echo "Unable to open\n"; } else { fwrite($fp, "GET / HTTP/1.0\r\n\r\n"); stream_set_timeout($fp, 2); $res = fread($fp, 2000); $info = stream_get_meta_data($fp); fclose($fp); if ($info['timed_out']) { echo 'Connection timed out!'; } else { echo $res; } } ?>

Nota: As of PHP 4.3, this function can (potentially) work on any kind of stream. In PHP 4.3, socket based streams are still the only kind supported in the PHP core, although streams from other extensions may support this function.

This function was previously called as set_socket_timeout() and later socket_set_timeout() but this usage is deprecated.

See also fsockopen() and fopen().

stream_set_write_buffer

(PHP 4 >= 4.3.0, PHP 5)

stream_set_write_buffer -- Sets file buffering on the given stream

Description

int stream_set_write_buffer ( resource stream, int buffer )

Output using fwrite() is normally buffered at 8K. This means that if there are two processes wanting to write to the same output stream (a file), each is paused after 8K of data to allow the other to write. stream_set_write_buffer() sets the buffering for write operations on the given filepointer stream to buffer bytes. If buffer is 0 then write operations are unbuffered. This ensures that all writes with fwrite() are completed before other processes are allowed to write to that output stream.

The function returns 0 on success, or EOF if the request cannot be honored.

The following example demonstrates how to use stream_set_write_buffer() to create an unbuffered stream.
Esempio 1. stream_set_write_buffer() example
<?php $fp = fopen($file, "w"); if ($fp) { stream_set_write_buffer($fp, 0); fwrite($fp, $output); fclose($fp); } ?>

stream_socket_accept

(PHP 5)

stream_socket_accept -- Accept a connection on a socket created by stream_socket_server()

Description

resource stream_socket_accept ( resource server_socket [, float timeout [, string &peername]] )

Accept a connection on a socket previously created by stream_socket_server(). If timeout is specified, the default socket accept timeout will be overridden with the time specified in seconds. The name (address) of the client which connected will be passed back in peername if included and available from the selected transport.

peername can also be determined later using stream_socket_get_name().

If the call fails, it will return FALSE.

Avvertimento

This function should not be used with UDP server sockets. Instead, use stream_socket_recvfrom() and stream_socket_sendto().

stream_socket_client

(PHP 5)

stream_socket_client -- Open Internet or Unix domain socket connection

Description

resource stream_socket_client ( string remote_socket [, int &errno [, string &errstr [, float timeout [, int flags [, resource context]]]]] )

Initiates a stream or datagram connection to the destination specified by remote_socket. The type of socket created is determined by the transport specified using standard URL formatting: transport://target. For Internet Domain sockets (AF_INET) such as TCP and UDP, the target portion of the remote_socket parameter should consist of a hostname or IP address followed by a colon and a port number. For Unix domain sockets, the target portion should point to the socket file on the filesystem. The optional timeout can be used to set a timeout in seconds for the connect system call. flags is a bitmask field which may be set to any combination of connection flags. Currently the selection of connection flags is limited to STREAM_CLIENT_CONNECT (default), STREAM_CLIENT_ASYNC_CONNECT and STREAM_CLIENT_PERSISTENT.

Nota: If you need to set a timeout for reading/writing data over the socket, use stream_set_timeout(), as the timeout parameter to stream_socket_client() only applies while connecting the socket.

stream_socket_client() returns a stream resource which may be used together with the other file functions (such as fgets(), fgetss(), fwrite(), fclose(), and feof()).

If the call fails, it will return FALSE and if the optional errno and errstr arguments are present they will be set to indicate the actual system level error that occurred in the system-level connect() call. If the value returned in errno is 0 and the function returned FALSE, it is an indication that the error occurred before the connect() call. This is most likely due to a problem initializing the socket. Note that the errno and errstr arguments will always be passed by reference.

Depending on the environment, the Unix domain or the optional connect timeout may not be available. A list of available transports can be retrieved using stream_get_transports(). See Appendice O for a list of built in transports.

The stream will by default be opened in blocking mode. You can switch it to non-blocking mode by using stream_set_blocking().
Esempio 1. stream_socket_client() Example
<?php $fp = stream_socket_client("tcp://www.example.com:80", $errno, $errstr, 30); if (!$fp) { echo "$errstr ($errno)<br />\n"; } else { fwrite($fp, "GET / HTTP/1.0\r\nHost: www.example.com\r\nAccept: */*\r\n\r\n"); while (!feof($fp)) { echo fgets($fp, 1024); } fclose($fp); } ?>
The example below shows how to retrieve the day and time from the UDP service "daytime" (port 13) in your own machine.
Esempio 2. Using UDP connection
<?php $fp = stream_socket_client("udp://127.0.0.1:13", $errno, $errstr); if (!$fp) { echo "ERROR: $errno - $errstr<br />\n"; } else { fwrite($fp, "\n"); echo fread($fp, 26); fclose($fp); } ?>

Avvertimento

UDP sockets will sometimes appear to have opened without an error, even if the remote host is unreachable. The error will only become apparent when you read or write data to/from the socket. The reason for this is because UDP is a "connectionless" protocol, which means that the operating system does not try to establish a link for the socket until it actually needs to send or receive data.

Nota: Nella specifica numerica degli indirizzi IPv6 (es. fe80::1) occorre racchiudere l'IP tra parentesi quadre. Ad esempio, tcp://[fe80::1]:80.

stream_socket_enable_crypto

(PHP 5 >= 5.1.0RC1)

stream_socket_enable_crypto -- Turns encryption on/off on an already connected socket

Description

mixed stream_socket_enable_crypto ( resource stream, bool enable [, int crypto_type [, resource session_stream]] )

When called with the crypto_type parameter, stream_socket_enable_crypto() will setup encryption on the stream using the specified method.

Valid values for crypto_type

STREAM_CRYPTO_METHOD_SSLv2_CLIENT
STREAM_CRYPTO_METHOD_SSLv3_CLIENT
STREAM_CRYPTO_METHOD_SSLv23_CLIENT
STREAM_CRYPTO_METHOD_TLS_CLIENT
STREAM_CRYPTO_METHOD_SSLv2_SERVER
STREAM_CRYPTO_METHOD_SSLv3_SERVER
STREAM_CRYPTO_METHOD_SSLv23_SERVER
STREAM_CRYPTO_METHOD_TLS_SERVER

Once the crypto settings are established, cryptography can be turned on and off dynamically by passing TRUE or FALSE in the enable parameter.

If this stream should be seeded with settings from an already established crypto enabled stream, pass that stream's resource variable in the fourth parameter.

Returns TRUE on success, FALSE if negotiation has failed or 0 if there isn't enough data and you should try again (only for non-blocking sockets).

Esempio 1. stream_socket_enable_crypto() Example

<?php
$fp = stream_socket_client("tcp://myproto.example.com:31337", $errno, $errstr, 30);
if (!$fp) {
  die("Unable to connect: $errstr ($errno)");
}
/* Turn on encryption for login phase */
stream_socket_enable_crypto($fp, true, STREAM_CRYPTO_METHOD_SSLv23_CLIENT);
fwrite($fp, "USER god\r\n");
fwrite($fp, "PASS secret\r\n");
/* Turn off encryption for the rest */
stream_socket_enable_crypto($fp, false);
while ($motd = fgets($fp)) {
  echo $motd;
}
fclose($fp);
?>

Riferimento C, OpenSSL Functions, and Appendice O

stream_socket_get_name

(PHP 5)

stream_socket_get_name -- Retrieve the name of the local or remote sockets

Description

string stream_socket_get_name ( resource handle, bool want_peer )

Returns the local or remote name of a given socket connection. If want_peer is set to TRUE the remote socket name will be returned, if it is set to FALSE the local socket name will be returned.

stream_socket_pair

(PHP 5 >= 5.1.0RC1)

stream_socket_pair -- Creates a pair of connected, indistinguishable socket streams

Descrizione

array stream_socket_pair ( int domain, int type, int protocol )

stream_socket_pair() creates a pair of connected, indistinguishable socket streams. This function is commonly used in IPC (Inter-Process Communication).

Elenco dei parametri

domain: The protocol family to be used: STREAM_PF_INET, STREAM_PF_INET6 or STREAM_PF_UNIX
type: The type of communication to be used: STREAM_SOCK_DGRAM, STREAM_SOCK_RAW, STREAM_SOCK_RDM, STREAM_SOCK_SEQPACKET or STREAM_SOCK_STREAM
protocol: The protocol to be used: STREAM_IPPROTO_ICMP, STREAM_IPPROTO_IP, STREAM_IPPROTO_RAW, STREAM_IPPROTO_TCP or STREAM_IPPROTO_UDP

Nota: Please consult the Streams constant list for further details on each constant.

Valori restituiti

Returns an array with the two socket resources on success, or FALSE on failure.

Esempi

Esempio 1. A stream_socket_pair() example
This example shows the basic usage of stream_socket_pair() in Inter-Process Comunication.
<?php $sockets = stream_socket_pair(STREAM_PF_UNIX, STREAM_SOCK_STREAM, STREAM_IPPROTO_IP); $pid = pcntl_fork(); if ($pid == -1) { die('could not fork'); } else if ($pid) { /* parent */ fclose($sockets[0]); fwrite($sockets[1], "child PID: $pid\n"); echo fgets($sockets[1]); fclose($sockets[1]); } else { /* child */ fclose($sockets[1]); fwrite($sockets[0], "message from child\n"); echo fgets($sockets[0]); fclose($sockets[0]); } ?>
Il precedente esempio visualizzerà qualcosa simile a:
child PID: 1378 message from child

stream_socket_recvfrom

(PHP 5)

stream_socket_recvfrom -- Receives data from a socket, connected or not

Description

string stream_socket_recvfrom ( resource socket, int length [, int flags [, string &address]] )

The function stream_socket_recvfrom() accepts data from a remote socket up to length bytes. If address is provided it will be populated with the address of the remote socket.

The value of flags can be any combination of the following:

Tabella 1. possible values for flags

`STREAM_OOB`	Process OOB (out-of-band) data.
`STREAM_PEEK`	Retrieve data from the socket, but do not consume the buffer. Subsequent calls to fread() or stream_socket_recvfrom() will see the same data.

Esempio 1. stream_socket_recvfrom() Example

<?php
/* Open a server socket to port 1234 on localhost */
$server = stream_socket_server('tcp://127.0.0.1:1234');

/* Accept a connection */
$socket = stream_socket_accept($server);

/* Grab a packet (1500 is a typical MTU size) of OOB data */
echo "Received Out-Of-Band: '" . stream_socket_recvfrom($socket, 1500, STREAM_OOB) . "'\n";

/* Take a peek at the normal in-band data, but don't comsume it. */
echo "Data: '" . stream_socket_recvfrom($socket, 1500, STREAM_PEEK) . "'\n";

/* Get the exact same packet again, but remove it from the buffer this time. */
echo "Data: '" . stream_socket_recvfrom($socket, 1500) . "'\n";

/* Close it up */
fclose($socket);
fclose($server);
?>

Nota: If a message received is longer than the length parameter, excess bytes may be discarded depending on the type of socket the message is received from (such as UDP).

stream_socket_sendto

(PHP 5)

stream_socket_sendto -- Sends a message to a socket, whether it is connected or not

Description

int stream_socket_sendto ( resource socket, string data [, int flags [, string address]] )

The function stream_socket_sendto() sends the data specified by data through the socket specified by socket. The address specified when the socket stream was created will be used unless an alternate address is specified in address.

The value of flags can be any combination of the following:

Tabella 1. possible values for flags

STREAM_OOB Process OOB (out-of-band) data.

Esempio 1. stream_socket_sendto() Example

<?php
/* Open a socket to port 1234 on localhost */
$socket = stream_socket_client('tcp://127.0.0.1:1234');

/* Send ordinary data via ordinary channels. */
fwrite($socket, "Normal data transmit.");

/* Send more data out of band. */
stream_socket_sendto($socket, "Out of Band data.", STREAM_OOB);

/* Close it up */
fclose($socket);
?>

stream_socket_server

(PHP 5)

stream_socket_server -- Create an Internet or Unix domain server socket

Description

resource stream_socket_server ( string local_socket [, int &errno [, string &errstr [, int flags [, resource context]]]] )

Creates a stream or datagram socket on the specified local_socket. The type of socket created is determined by the transport specified using standard URL formatting: transport://target. For Internet Domain sockets (AF_INET) such as TCP and UDP, the target portion of the remote_socket parameter should consist of a hostname or IP address followed by a colon and a port number. For Unix domain sockets, the target portion should point to the socket file on the filesystem. flags is a bitmask field which may be set to any combination of socket creation flags. The default value of flags is STREAM_SERVER_BIND | STREAM_SERVER_LISTEN.

Nota: For UDP sockets, you must use STREAM_SERVER_BIND as the flags parameter.

This function only creates a socket, to begin accepting connections use stream_socket_accept().

If the call fails, it will return FALSE and if the optional errno and errstr arguments are present they will be set to indicate the actual system level error that occurred in the system-level socket(), bind(), and listen() calls. If the value returned in errno is 0 and the function returned FALSE, it is an indication that the error occurred before the bind() call. This is most likely due to a problem initializing the socket. Note that the errno and errstr arguments will always be passed by reference.

Depending on the environment, Unix domain sockets may not be available. A list of available transports can be retrieved using stream_get_transports(). See Appendice O for a list of bulitin transports.

Esempio 1. Using TCP server sockets
<?php $socket = stream_socket_server("tcp://0.0.0.0:8000", $errno, $errstr); if (!$socket) { echo "$errstr ($errno)<br />\n"; } else { while ($conn = stream_socket_accept($socket)) { fwrite($conn, 'The local time is ' . date('n/j/Y g:i a') . "\n"); fclose($conn); } fclose($socket); } ?>

The example below shows how to act as a time server which can respond to time queries as shown in an example on stream_socket_client().

Nota: Most systems require root access to create a server socket on a port below 1024.

Esempio 2. Using UDP server sockets

<?php
$socket = stream_socket_server("udp://127.0.0.1:1113", $errno, $errstr, STREAM_SERVER_BIND);
if (!$socket) {
    die("$errstr ($errno)");
}

do {
    $pkt = stream_socket_recvfrom($socket, 1, 0, $peer);
    echo "$peer\n";
    stream_socket_sendto($socket, date("D M j H:i:s Y\r\n"), 0, $peer);
} while ($pkt !== false);

?>

Nota: Nella specifica numerica degli indirizzi IPv6 (es. fe80::1) occorre racchiudere l'IP tra parentesi quadre. Ad esempio, tcp://[fe80::1]:80.

stream_wrapper_register

(PHP 4 >= 4.3.2, PHP 5)

stream_wrapper_register -- Register a URL wrapper implemented as a PHP class

Description

bool stream_wrapper_register ( string protocol, string classname )

stream_wrapper_register() allows you to implement your own protocol handlers and streams for use with all the other filesystem functions (such as fopen(), fread() etc.).

To implement a wrapper, you need to define a class with a number of member functions, as defined below. When someone fopens your stream, PHP will create an instance of classname and then call methods on that instance. You must implement the methods exactly as described below - doing otherwise will lead to undefined behaviour.

Nota: As of PHP 5.0.0 the instance of classname will be populated with a context property referencing a Context Resource which may be accessed with stream_context_get_options(). If no context was passed to the stream creation function, context will be set to NULL.

stream_wrapper_register() will return FALSE if the protocol already has a handler.

bool stream_open ( string path, string mode, int options, string opened_path )

This method is called immediately after your stream object is created. path specifies the URL that was passed to fopen() and that this object is expected to retrieve. You can use parse_url() to break it apart.

mode is the mode used to open the file, as detailed for fopen(). You are responsible for checking that mode is valid for the path requested.

options holds additional flags set by the streams API. It can hold one or more of the following values OR'd together.

Flag	Description
STREAM_USE_PATH	If `path` is relative, search for the resource using the include_path.
STREAM_REPORT_ERRORS	If this flag is set, you are responsible for raising errors using trigger_error() during opening of the stream. If this flag is not set, you should not raise any errors.

If the path is opened successfully, and STREAM_USE_PATH is set in options, you should set opened_path to the full path of the file/resource that was actually opened.

If the requested resource was opened successfully, you should return TRUE, otherwise you should return FALSE

void stream_close ( void )

This method is called when the stream is closed, using fclose(). You must release any resources that were locked or allocated by the stream.

string stream_read ( int count )

This method is called in response to fread() and fgets() calls on the stream. You must return up-to count bytes of data from the current read/write position as a string. If there are less than count bytes available, return as many as are available. If no more data is available, return either FALSE or an empty string. You must also update the read/write position of the stream by the number of bytes that were successfully read.

int stream_write ( string data )

This method is called in response to fwrite() calls on the stream. You should store data into the underlying storage used by your stream. If there is not enough room, try to store as many bytes as possible. You should return the number of bytes that were successfully stored in the stream, or 0 if none could be stored. You must also update the read/write position of the stream by the number of bytes that were successfully written.

bool stream_eof ( void )

This method is called in response to feof() calls on the stream. You should return TRUE if the read/write position is at the end of the stream and if no more data is available to be read, or FALSE otherwise.

int stream_tell ( void )

This method is called in response to ftell() calls on the stream. You should return the current read/write position of the stream.

bool stream_seek ( int offset, int whence )

This method is called in response to fseek() calls on the stream. You should update the read/write position of the stream according to offset and whence. See fseek() for more information about these parameters. Return TRUE if the position was updated, FALSE otherwise.

bool stream_flush ( void )

This method is called in response to fflush() calls on the stream. If you have cached data in your stream but not yet stored it into the underlying storage, you should do so now. Return TRUE if the cached data was successfully stored (or if there was no data to store), or FALSE if the data could not be stored.

array stream_stat ( void )

This method is called in response to fstat() calls on the stream and should return an array containing the same values as appropriate for the stream.

bool unlink ( string path )

This method is called in response to unlink() calls on URL paths associated with the wrapper and should attempt to delete the item specified by path. It should return TRUE on success or FALSE on failure. In order for the appropriate error message to be returned, do not define this method if your wrapper does not support unlinking.

Nota: Userspace wrapper unlink method is not supported prior to PHP 5.0.0.

bool rename ( string path_from, string path_to )

This method is called in response to rename() calls on URL paths associated with the wrapper and should attempt to rename the item specified by path_from to the specification given by path_to. It should return TRUE on success or FALSE on failure. In order for the appropriate error message to be returned, do not define this method if your wrapper does not support renaming.

Nota: Userspace wrapper rename method is not supported prior to PHP 5.0.0.

bool mkdir ( string path, int mode, int options )

This method is called in response to mkdir() calls on URL paths associated with the wrapper and should attempt to create the directory specified by path. It should return TRUE on success or FALSE on failure. In order for the appropriate error message to be returned, do not define this method if your wrapper does not support creating directories. Posible values for options include STREAM_REPORT_ERRORS and STREAM_MKDIR_RECURSIVE.

Nota: Userspace wrapper mkdir method is not supported prior to PHP 5.0.0.

bool rmdir ( string path, int options )

This method is called in response to rmdir() calls on URL paths associated with the wrapper and should attempt to remove the directory specified by path. It should return TRUE on success or FALSE on failure. In order for the appropriate error message to be returned, do not define this method if your wrapper does not support removing directories. Possible values for options include STREAM_REPORT_ERRORS.

Nota: Userspace wrapper rmdir method is not supported prior to PHP 5.0.0.

bool dir_opendir ( string path, int options )

This method is called immediately when your stream object is created for examining directory contents with opendir(). path specifies the URL that was passed to opendir() and that this object is expected to explore. You can use parse_url() to break it apart.

array url_stat ( string path, int flags )

This method is called in response to stat() calls on the URL paths associated with the wrapper and should return as many elements in common with the system function as possible. Unknown or unavailable values should be set to a rational value (usually 0).

flags holds additional flags set by the streams API. It can hold one or more of the following values OR'd together.

Flag	Description
STREAM_URL_STAT_LINK	For resources with the ability to link to other resource (such as an HTTP Location: forward, or a filesystem symlink). This flag specified that only information about the link itself should be returned, not the resource pointed to by the link. This flag is set in response to calls to lstat(), is_link(), or filetype().
STREAM_URL_STAT_QUIET	If this flag is set, your wrapper should not raise any errors. If this flag is not set, you are responsible for reporting errors using the trigger_error() function during stating of the path.

string dir_readdir ( void )

This method is called in response to readdir() and should return a string representing the next filename in the location opened by dir_opendir().

bool dir_rewinddir ( void )

This method is called in response to rewinddir() and should reset the output generated by dir_readdir(). i.e.: The next call to dir_readdir() should return the first entry in the location returned by dir_opendir().

bool dir_closedir ( void )

This method is called in response to closedir(). You should release any resources which were locked or allocated during the opening and use of the directory stream.

The example below implements a var:// protocol handler that allows read/write access to a named global variable using standard filesystem stream functions such as fread(). The var:// protocol implemented below, given the URL "var://foo" will read/write data to/from $GLOBALS["foo"].
Esempio 1. A Stream for reading/writing global variables
<?php class VariableStream { var $position; var $varname; function stream_open($path, $mode, $options, &$opened_path) { $url = parse_url($path); $this->varname = $url["host"]; $this->position = 0; return true; } function stream_read($count) { $ret = substr($GLOBALS[$this->varname], $this->position, $count); $this->position += strlen($ret); return $ret; } function stream_write($data) { $left = substr($GLOBALS[$this->varname], 0, $this->position); $right = substr($GLOBALS[$this->varname], $this->position + strlen($data)); $GLOBALS[$this->varname] = $left . $data . $right; $this->position += strlen($data); return strlen($data); } function stream_tell() { return $this->position; } function stream_eof() { return $this->position >= strlen($GLOBALS[$this->varname]); } function stream_seek($offset, $whence) { switch ($whence) { case SEEK_SET: if ($offset < strlen($GLOBALS[$this->varname]) && $offset >= 0) { $this->position = $offset; return true; } else { return false; } break; case SEEK_CUR: if ($offset >= 0) { $this->position += $offset; return true; } else { return false; } break; case SEEK_END: if (strlen($GLOBALS[$this->varname]) + $offset >= 0) { $this->position = strlen($GLOBALS[$this->varname]) + $offset; return true; } else { return false; } break; default: return false; } } } stream_wrapper_register("var", "VariableStream") or die("Failed to register protocol"); $myvar = ""; $fp = fopen("var://myvar", "r+"); fwrite($fp, "line1\n"); fwrite($fp, "line2\n"); fwrite($fp, "line3\n"); rewind($fp); while (!feof($fp)) { echo fgets($fp); } fclose($fp); var_dump($myvar); ?>

stream_wrapper_restore

(PHP 5 >= 5.1.0RC1)

stream_wrapper_restore -- Restores a previously unregistered built-in wrapper

Description

bool stream_wrapper_restore ( string protocol )

Restores a built-in wrapper previously unregistered with stream_wrapper_unregister().

stream_wrapper_unregister

(PHP 5 >= 5.1.0RC1)

stream_wrapper_unregister -- Unregister a URL wrapper

Description

bool stream_wrapper_unregister ( string protocol )

stream_wrapper_unregister() allows you to disable an already defined stream wrapper. Once the wrapper has been disabled you may override it with a user-defined wrapper using stream_wrapper_register() or reenable it later on with stream_wrapper_restore().

CXLV. Stringhe

Introduzione

Queste funzioni permettono di manipolare le stringhe in vari modi. Ulteriori funzioni specializzate possono essere trovate nel capitolo dedicato alle espressioni regolari e nel capitolo trattamento degli URL.

Per dettagli su come si comportano le stringhe, in particolare a riguardo l'uso degli apici singoli, doppi apici, e sequenze di escape, vedere il paragrafo Stringhe nel capitolo Tipi del manuale.

Requisiti

Non sono necessarie librerie esterne per utilizzare questo modulo.

Installazione

Non è necessaria nessuna installazione per usare queste funzioni, esse fanno parte del core di PHP.

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

CRYPT_SALT_LENGTH integer
CRYPT_STD_DES integer
CRYPT_EXT_DES integer
CRYPT_MD5 integer
CRYPT_BLOWFISH integer
HTML_SPECIALCHARS (integer)
HTML_ENTITIES (integer)
ENT_COMPAT (integer)
ENT_QUOTES (integer)
ENT_NOQUOTES (integer)
CHAR_MAX (integer)
LC_CTYPE (integer)
LC_NUMERIC (integer)
LC_TIME (integer)
LC_COLLATE (integer)
LC_MONETARY (integer)
LC_ALL (integer)
LC_MESSAGES (integer)
STR_PAD_LEFT (integer)
STR_PAD_RIGHT (integer)
STR_PAD_BOTH (integer)

Vedere anche:

Per funzioni più potenti nel gestire e manipolare le stringhe vedere anche i capitoli Funzioni per espressioni regolari POSIX e Funzioni per espressioni regolari compatibili Perl.

Sommario
addcslashes -- Esegue il quoting di una stringa con gli slash nello stile del C
addslashes -- Esegue il quoting di una stringa con gli slash '/'
bin2hex -- Converte i dati binari nella rappresentazione esadecimale
chop -- Alias di di rtrim()
chr -- Restituisce un carattere specifico
chunk_split -- Divide una stringa in segmento più piccoli
convert_cyr_string -- Converte da un set di caratteri Cirillico ad un'altro
convert_uudecode -- Decodifica una stringa codificata con uuencode
convert_uuencode -- Codifica uuencode di una stringa
count_chars -- Restituisce informazioni sui caratteri usati in una stringa
crc32 -- Calcola il crc32 polinomiale di una stringa
crypt -- Criptazione di una stringa a senso unico (hashing)
echo -- Visualizza una o più stringhe
explode -- Suddivide una stringa
fprintf -- Scrive una stringa formattata in uno stream
get_html_translation_table -- Restituisce la tabella di decodifica utilizzata da htmlspecialchars() e htmlentities()
hebrev -- Converte il testo logico Ebraico in testo visuale
hebrevc -- Converte il testo logico Ebraico in testo visuale con conversione del carattere di 'a capo'
html_entity_decode -- Converte le entità HTML nei corrispondenti caratteri
htmlentities -- Converte tutti i possibili caratteri in entità HTML
htmlspecialchars_decode -- Convert special HTML entities back to characters
htmlspecialchars -- Converte i caratteri speciali in entità HTML
implode -- Unisce gli elementi di una matrice in una stringa
join -- Alias di di implode()
levenshtein -- Calcola la distanza Levenshtein tra due stringhe
localeconv -- Ottiene informazioni sul formato numerico
ltrim -- Rimuove gli spazi (o altri caratteri) dall'inizio di una stringa
md5_file -- Calcola l'hash md5 del file dato
md5 -- Calcola il valore md5 di una stringa
metaphone -- Calcola la chiave metaphone di una stringa
money_format -- Formattazione di un numero come stringa monetaria
nl_langinfo -- Ricava informazioni sulla lingua e le impostazioni locali
nl2br -- Inserisce il tag HTML di 'a capo' prima di tutti i caratteri di 'a capo' della stringa
number_format -- Formatta un numero con i grupppi delle migliaia
ord -- Restituisce il valore ASCII di un carattere
parse_str -- Suddivide una stringa in variabili
print -- Visualizza una stringa
printf -- Visualizza una stringa formattata
quoted_printable_decode -- Converte una stringa 'quoted-printable' in una stringa a 8 bit
quotemeta -- Quota i meta caratteri
rtrim -- Rimuove gli spazi (ed altri caratteri) dalla fine della stringa
setlocale -- Imposta i parametri di localizzazione
sha1_file -- Calcola l'hash sha1 di un file
sha1 -- Calcola l'hash sha1 di una stringa
similar_text -- Calcola la similitudine tra due stringhe
soundex -- Calcola la chiave soundex di una data stringa
sprintf -- Restituisce una stringa formattata
sscanf -- Analizza l'input da una string in base al formato
str_ireplace -- Versione insensibile alle miuscole/minuscole di str_replace()
str_pad -- Riempie una stringa con un'altra stringa portando la prima ad una lunghezza pre-determinata
str_repeat -- Ripete una stringa
str_replace -- Sostituisce tutte le occorrenze della stringa cercata con la stringa di sostituzione
str_rot13 -- Esegue la trasformazione rot13 di una stringa
str_shuffle -- Mischia una stringa in modo casuale
str_split -- Converte una stringa in una matrice
str_word_count -- Restituisce informazioni sulle parole utilizzate in una stringa
strcasecmp -- Confronto non sensibile alle maiuscole e sicuro con i dati binari
strchr -- Alias di strstr()
strcmp -- Confronto tra stringhe affidabile con dati binari
strcoll -- Confronto tra stringhe basato sulle impostazioni locali
strcspn -- Trova la lunghezza del segmento iniziale che non soddisfa una maschera
strip_tags -- Rimuove i tag HTML e PHP da una stringa
stripcslashes -- Rimuove gli slash aggiunti con addcslashes()
stripos -- Trova la prima occorrenza in una stringa senza distinzione tra maiuscole e minuscole
stripslashes -- Rimuove gli slash aggiunti con addslashes()
stristr -- Versione insensibile alle maiuscole/minuscole di strstr()
strlen -- Restituisce la lunghezza di una stringa
strnatcasecmp -- Versione insensibile alle maiuscole/minuscole di confronto tra stringhe tramite l'algoritmo dell"ordine naturale"
strnatcmp -- Confronto tra stringhe con l'algoritmo dell' "ordine naturale"
strncasecmp -- Confronto sicuro con i testi binari, insensibile alle lettere maiuscole/minuscole sui primi n caratteri
strncmp -- Confronto tra stringhe sui primi n caratteri, sicuro con i dati binari
strpbrk -- Ricerca in una stringa uno qualsiasi dei caratteri di un dato set
strpos -- Trova la posizione della prima occorrenza di una stringa
strrchr -- Trova l'ultima occorrenza di un carattere in una stringa
strrev -- Inverte una stringa
strripos -- Trova la posizione dell'ultima occorrenza di una stringa in un'altra indipendentemente dalle lettere minuscole/maiusole
strrpos -- Trova la posizione dell'ultima occorrenza di un carattere in una stringa
strspn -- Trova la lunghezza di un testo che corrisponde alla maschera data
strstr -- Trova la prima occorrenza di una stringa
strtok -- Suddivide una stringa in token
strtolower -- Converte in minuscolo una stringa
strtoupper -- Converte in maiuscolo una stringa
strtr -- Traduce certi caratteri
substr_compare -- Confronto tra due stringhe a partire da una data posizione per n caratteri, sicuro con i dati binari e, opzionalmente, senza distinguere tra lettere maiuscole e minuscole
substr_count -- Conta il numero di occorrenze di un segmento di stringa
substr_replace -- Sostuisce una porzione di testo
substr -- Restituisce parte di una stringa
trim -- Rimuove gli spazi (ed altri caratteri) all'inizio e alla fine di un testo
ucfirst -- Converte in maiuscolo il primo carattere del testo
ucwords -- Converte in maiuscolo il primo carattere di ogni parola di una stringa
vfprintf -- Scrive una stringa formatta in un flusso
vprintf -- Visualizza una stringa formattata
vsprintf -- Restituisce una stringa formattata
wordwrap -- Divide una stringa ad un certo numero di caratteri utilizzando il carattere di divisione

addcslashes

(PHP 4, PHP 5)

addcslashes -- Esegue il quoting di una stringa con gli slash nello stile del C

Descrizione

string addcslashes ( string str, string charlist )

La funzione restituisce una stringa con il carattere di backslash '\' anteposto ai caratteri che sono indicati nel parametro charlist. La funzione inserisce il carattere di escape nello stile C in caso di \n, \r ecc., in caso di caratteri con codifica ASCII minore di 32 o superiore a 126 si applica la conversione nella rappresentazione ottale.

Occorre prestare attenzione se si imposta di anteporre il carattere di escape ai caratteri 0, a, b, f, n, r, t e v. Questi saranno convertiti in \0, \a, \b, \f, \n, \r, \t e \v. In PHP \0 (NULL), \r (carriage return), \n (newline) e \t (tab) sono sequenze di escape predefinite, anche in C tutte queste sono sequenze di escape predefinite.

Valorizzare il parametro charlist con "\0..\37", significa che si vuole inserire il carattere di escape davanti ai caratteri la cui codifica ASCII è comprese tra 0 e 31.
Esempio 1. Esempio di uso di addcslashes()
<?php $escaped = addcslashes($not_escaped, "\0..\37!@\177..\377"); ?>

Quando si definisca una sequenza di caratteri nel parametro charlist occorre essere consapevoli di quali caratteri sono compresi nel range.

<?php
echo addcslashes('foo[ ]', 'A..z');
// output:  \f\o\o\[ \]
// Inserisce l'escape davanti a tutti i caratteri maiuscoli e minuscoli
// ... ma anche [\]^_` i tab, line
// feeds, carriage returns, etc.
?>

Inoltre, se il primo carattere di un range ha una codifica ASCII maggiore del secondo, il range non sarà applicato. Soltanto il primo, i punti, e l'ultimo carattere avrà la sequenza di escape. Utilizzare la funzione ord() per ottenere la codifica ASCII di un carattere.

<?php
echo addcslashes("zoo['.']", 'z..A');
// output:  \zoo['\.']
?>

Vedere anche stripcslashes(), stripslashes(), htmlspecialchars() e quotemeta().

addslashes

(PHP 3, PHP 4, PHP 5)

addslashes -- Esegue il quoting di una stringa con gli slash '/'

Descrizione

string addslashes ( string str )

La funzione restituisce una stringa con il carattere di backslah '\' anteposto ai caratteri che richiedono il quoting nelle query dei database. Questi caratteri sono: apici singoli ('), doppi apici ("), backslash (\) e NUL (il byte NULL).

Un esempio di utilizzo di addslashes() è dato dal caso in cui si inserisce dei dati in un database. Ad esempio, per inserire il nome O'reilly in un database, occorre anteporre il carattere di escape. Molti database eseguono questo compito con il carattere \, quindi il nostro esempio diventerebbe O\'reilly. Questo serve solo per inserire i dati nel database, il carattere in più \ non sarà inserito. Impostando la direttiva PHP magic_quotes_sybase a on si indica che ' deve essere preceduto da un'altro '.

La direttiva PHP magic_quotes_gpc è impostata a on per default, ed in pratica esegue addslashes() su tutti i dati GET, POST, e COOKIE. Non utilizzare addslashes() su stringhe che hanno già il carattere di escape per via del parametro magic_quotes_gpc altrimenti si ottiene un doppio escape. La funzione get_magic_quotes_gpc() può aiutare nella verifica di questa situazione.

Esempio 1. Esempio di uso di addslashes()
<?php $str = "Is your name O'reilly?"; // Outputs: Is your name O\'reilly? echo addslashes($str); ?>

Vedere anche stripslashes(), htmlspecialchars(), quotemeta() e get_magic_quotes_gpc().

bin2hex

(PHP 3 >= 3.0.9, PHP 4, PHP 5)

bin2hex -- Converte i dati binari nella rappresentazione esadecimale

Descrizione

string bin2hex ( string str )

La funzione restituisce una stringa ASCII contenente la rappresentazione esadecimale del parametro str. La conversione viene eseguita byte per byte considerando prima il semi-byte più significativo.

Vedere anche pack() e unpack().

chop

(PHP 3, PHP 4, PHP 5)

chop -- Alias di di rtrim()

Descrizione

This function is an alias of: rtrim().

Nota: chop() è differente rispetto alla omonima funzione di Perl chop(), la quale rimuove l'ultimo carattere della stringa.

chr

(PHP 3, PHP 4, PHP 5)

chr -- Restituisce un carattere specifico

Descrizione

string chr ( int ascii )

La funzione restituisce una stringa di un carattere contenente il carattere indicato come codifica ASCII nel parametro ascii.
Esempio 1. Esempio di uso di chr()
<?php $str = "La stringa termina con un escape: "; $str .= chr(27); /* aggiunge il carattere di escape al termine di $str */ /* Spesso è più pratico */ $str = sprintf("The string ends in escape: %c", 27); ?>

A questo link http://www.asciitable.com si può trovare una tavola delle codifiche ASCII.

Questa funzione è complementare rispetto a ord(). Vedere anche sprintf() con la stringa di formato %c.

chunk_split

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

chunk_split -- Divide una stringa in segmento più piccoli

Descrizione

string chunk_split ( string body [, int chunklen [, string end]] )

Questa funzione può essere utilizzata per suddividere una stringa in segmenti più ridotti, per possono essere utili, ad esempio, nel convertire l'output della funzione base64_encode() in modo da aderire alle specifiche indicate nella RFC 2045. La funzione inserisce end (il default è "\r\n") ad ogni chunklen caratteri (default è 76). La funzione restituisce una nuova stringa lasciando inalterata la stringa originale.
Esempio 1. Esempio di uso di chunk_split()
<?php // format $data using RFC 2045 semantics $new_string = chunk_split(base64_encode($data)); ?>

Vedere anche str_split(), explode(), split(), wordwrap() e RFC 2045.

convert_cyr_string

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

convert_cyr_string -- Converte da un set di caratteri Cirillico ad un'altro

Descrizione

string convert_cyr_string ( string str, string from, string to )

Questa funzione restituisce la stringa data convertita da un set di caratteri Cirillico ad un altro. I parametri from e to rappresentano il set di caratteri Cirillici di origine e di destinazione. I tipi supportati sono:

k - koi8-r
w - windows-1251
i - iso8859-5
a - x-cp866
d - x-cp866
m - x-mac-cyrillic

Nota: Questa funzione è binary-safe (gestisce correttamente i file binari)

convert_uudecode

(PHP 5)

convert_uudecode -- Decodifica una stringa codificata con uuencode

Descrizione

La funzione crypt() restituisce una stringa criptata tramite l'algoritmo standard di crittografia di UNIX basato sul DES o su algoritmo alternativi disponibili sul sistema. I parametri sono la stringa che deve essere crittografata, e un parametro opzionale da usarsi come base per la crittografia. Vedere le pagine Unix relative alla funzione cript per maggiori dettagli.

Se il parametro salt non viene fornito, il PHP ne genererà uno casuale ad ogni chiamata.

Alcuni sistemi operativi supportano più di un tipo di cifratura. Infatti in alcuni casi lo standard basato sul DES viene sostituito da un algoritmo basato su MD5. Il tipo di crittografia da utilizzare viene attivato tramite il parametro salt. Al momento dell'installazione il PHP cerca di determinare le caratteristiche della funzione crypt e accetterà salt per altri tipi di funzioni. Se il parametro salt non viene passato, il PHP genererà, per default, una chiave di due caratteri a meno che il sistema di cifratura di default del sistema non sia MD5, in questo caso si genererà una chiave casuale compatibile con MD5. Il PHP imposta una costante chiamata CRYPT_SALT_LENGTH dalla quale si può sapere se sul sistema si può utilizzare una chiave di due caratteri o la chiave più lunga di 12 caratteri.

Se si usa la chiave generata, bisogna fare attenzione che questa viene generata una sola volta. Se si chiama la funzione ricorsivamente, si possono avere dei problemi di formato e di sicurezza.

La crittografia basa sullo standard DES restituisce la chiave come primi due caratteri dell'output. Inoltre utilizza solo i primi 8 caratteri del parametro str, pertanto stringhe più lunghe che inizino con i medesimi otto caratteri, creeranno il medesimo risultato (se si utilizza la medesima chiave).

Sui sistemi nei quali la funzione cript() supporta più tipi di crittografia, si imposteranno le seguenti costanti a 0 o a 1 in base al tipo disponibile.

CRYPT_STD_DES - Standard basato su DES con chiave di due caratteri
CRYPT_EXT_DES - Estensione basato su DES con chiave di nove caratteri
CRYPT_MD5 - Crittografia basata su MD5 con 12 caratteri di chiave inizianti con $1$
CRYPT_BLOWFISH - Crittografia Blowfish con 16 caratteri di chiave inizianti con $2$ oppure $2a$

Nota: Non esiste una funzione di decriptazione, poiché crypt() è un algoritmo ad una via.

Esempio 1. Esempio di uso di crypt()

<?php
$password = crypt("My1sTpassword"); // let salt be generated

/* Si dovrebbe passare l'intero risultato di crypt() come chiave di confronto
   della password per evitare problemi con differenti algoritmi di hash. (Come detto prima
   lo standard basato su DES usa chiavi di 2 caratteri,
   mentre lo standard basato su MD5 ne usa 12). */
if (crypt($user_input, $password) == $password) {
   echo "Password verified!";
}
?>

Esempio 2. Utilizzo di crypt() con htpasswd

<?php
// Set the password
$password = 'mypassword';
 
// Get the hash, letting the salt be automatically generated
$hash = crypt($password);
?>

Esempio 3. Uso dei diversi tipi di criptazione

<?php
if (CRYPT_STD_DES == 1) {
    echo 'Standard DES: ' . crypt('rasmuslerdorf', 'rl') . "\n";
}
 
if (CRYPT_EXT_DES == 1) {
    echo 'Extended DES: ' . crypt('rasmuslerdorf', '_J9..rasm') . "\n";
}
 
if (CRYPT_MD5 == 1) {
    echo 'MD5:          ' . crypt('rasmuslerdorf', '$1$rasmusle$') . "\n";
}
 
if (CRYPT_BLOWFISH == 1) {
    echo 'Blowfish:     ' . crypt('rasmuslerdorf', '$2a$07$rasmuslerd...........$') . "\n";
}
?>

Il precedente esempio visualizzerà qualcosa simile a:

Standard DES: rl.3StKT.4T8M
Extended DES: _J9..rasmBYk8r9AiWNc
MD5:          $1$rasmusle$rISCgZzpwk3UhDidwXvin0
Blowfish:     $2a$07$rasmuslerd............nIdrcHdxcUxWomQX9j6kvERCFjTg7Ra

Vedere anche md5() e il modulo Mcrypt.

echo

(PHP 3, PHP 4, PHP 5)

echo -- Visualizza una o più stringhe

Descrizione

void echo ( string arg1 [, string ...] )

Visualizza tutti i parametri.

echo() in realtà non è una funzione (è un costrutto del linguaggio) pertanto non richiede l'uso di parametri. Infatti, se si vuole passare più di un parametro, non bisogna racchiuderli tra parentesi.

Esempio 1. Esempi di uso di echo()
<?php echo "Hello World"; echo "This spans multiple lines. The newlines will be output as well"; echo "This spans\nmultiple lines. The newlines will be\noutput as well."; echo "Escaping characters is done \"Like this\"."; // Si possono utilizzare variabili all'interno dei parametri di echo $foo = "foobar"; $bar = "barbaz"; echo "foo is $foo"; // foo is foobar // Si possono utilizzare anche delle matrici $bar = array("value" => "foo"); echo "this is {$bar['value']} !"; // this is foo ! // Utilizzando gli apici singoli viene visualizzato il nome della variabile, non il valore echo 'foo is $foo'; // foo is $foo // Se non vi sono altri caratteri, si può visualizzare soltanto il contenuto delle variabili echo $foo; // foobar echo $foo,$bar; // foobarbarbaz // Alcuni programmatori preferiscono passare i parametri come sequenza di stringhe concatenate. echo 'This ', 'string ', 'was ', 'made ', 'with multiple parameters.', chr(10); echo 'This ' . 'string ' . 'was ' . 'made ' . 'with concatenation.' . "\n"; echo <<<END Questo esempio utilizza la sintassi "here document" per visualizzare più linee oltre al contenuto di $variable Notare che il terminatore del testo richiede anche il punto e virgola, senza alcun spazio aggiuntivo! END; // Poichè echo non è una funzione la seguente riga non è valida. ($some_var) ? echo 'true' : echo 'false'; // Tuttavia la seguente funziona ($some_var) ? print('true'): print('false'); // print è una funzione echo $some_var ? 'true': 'false'; // altra versione dell'istruzione ?>

echo() ha una sintassi alternativa abbreviata in cui si può fare seguire alle tag di apertura il segno di uguale. Questa sintassi abbreviata funziona solo se il parametro di configurazione short_open_tag è abilitato.

I have <?=$foo?> foo.

Per una breve discussione sulle differenze tra print() e echo(), vedere FAQTs Knowledge Base Article: http://www.faqts.com/knowledge_base/view.phtml/aid/1/fid/40

Nota: Poichè questo è un costrutto del linguaggio e non una funzione, non può essere chiamato con le variabili funzione

Vedere anche print(), printf() e flush().

explode

(PHP 3, PHP 4, PHP 5)

explode -- Suddivide una stringa

Descrizione

array explode ( string separator, string string [, int limit] )

Questa funzione restituisce una matrice di stringhe, ciascuna delle quali è una parte di string ottenuta dividendo la stringa originale utilizzando separator come separatore di stringa. Se si imposta limit la matrice restituita conterrà al massimo limit elementi di cui l'ultimo conterrà la parte restante di string.

Se il parametro separator è impostato ad una stringa vuota (""), la funzione explode() restituirà FALSE. Se separator contiene caratteri non presenti in string, allora explode() restituirà una matrice contenente string.

Se il parametro limit è negativo, sono restituiti tutti i componenti tranne gli ultimi limit elementi. Questa caratteristica è stata inserita in PHP 5.1.0.

Sebbene implode() può, per ragioni storiche, accettare i parametri in entrambi gli ordini, explode() non può. Occorre accertarsi che il parametro separator sia antecedente al parametro string.

Nota: Il parametro limit è stato aggiunto dalla versione 4.0.1

Esempio 1. Esempi di uso di explode()
<?php // Esempio 1 $pizza = "piece1 piece2 piece3 piece4 piece5 piece6"; $pieces = explode(" ", $pizza); echo $pieces[0]; // piece1 echo $pieces[1]; // piece2 // Esempio 2 $data = "foo:*:1023:1000::/home/foo:/bin/sh"; list($user, $pass, $uid, $gid, $gecos, $home, $shell) = explode(":", $data); echo $user; // foo echo $pass; // * ?>

Nota: Questa funzione è binary-safe (gestisce correttamente i file binari)

Vedere anche preg_split(), spliti(), split(), strtok() e implode().

fprintf

(PHP 5)

fprintf -- Scrive una stringa formattata in uno stream

Descrizione

int fprintf ( resource handle, string format [, mixed args [, mixed ...]] )

La funzione scrive una stringa formattata in base al parametro format nello stream indicato dal parametro handle. I valori per il parametro format sono descritti nella documentazione della funzione sprintf().

Restituisce la lunghezza della stringa prodotta.

Vedere anche: printf(), sprintf(), sscanf(), fscanf(), vsprintf() e number_format().

Esempi

Esempio 1. fprintf(): interi completati con zero
<?php if (!($fp = fopen('date.txt', 'w'))) return; fprintf($fp, "%04d-%02d-%02d", $year, $month, $day); // Scrive la data in formato ISO nel file date.txt ?>

Esempio 2. fprintf(): formattazione della moneta
<?php if (!($fp = fopen('currency.txt', 'w'))) return; $money1 = 68.75; $money2 = 54.35; $money = $money1 + $money2; // echo $money will output "123.1"; $len = fprintf($fp, '%01.2f', $money); // scrive "123.10" nel file currency.txt echo "wrote $len bytes to currency.txt"; // utilizza il valore restituito da fprintf per stabilire quanti byte sono stati scritti ?>

get_html_translation_table

(PHP 4, PHP 5)

get_html_translation_table -- Restituisce la tabella di decodifica utilizzata da htmlspecialchars() e htmlentities()

Descrizione

array get_html_translation_table ( [int table [, int quote_style]] )

La funzione get_html_translation_table() restituisce la tabella di decodifica utilizzata dalle funzioni htmlspecialchars() e htmlentities().

Esistono due nuove costanti (HTML_ENTITIES, HTML_SPECIALCHARS) che permettono di indicare quale tabella sid esidera. Inoltre nelle funzioni htmlspecialchars() e htmlentities(), opzionalmente, si può specificare il quote_style con cui si lavora. Il default è ENT_COMPAT. Vedere la descrizione di queste modalità in htmlspecialchars().

Esempio 1. Esempio della tabella di decodifica
<?php $trans = get_html_translation_table(HTML_ENTITIES); $str = "Hallo & <Frau> & Krämer"; $encoded = strtr($str, $trans); ?>
La variabile $encoded ora contiene: "Hallo & <Frau> & Krämer".

Un'altro utilizzo interessante di questa funzione è dato, in combinazione con array_flip(), dalla possibilità di cambiare direzione alla decodifica.

<?php
$trans = array_flip($trans);
$original = strtr($encoded, $trans);
?>

La funzione html_entity_decode() è l'opposto di htmlentities() converte tutte le entità HTML presenti nel parametro string nel corrispondente carattere.

Il secondo parametro, quote_style, opzionale, indica cosa occorre fare per gli apici 'singoli' e "doppi". Sono possibili tre scelte indicate da tre costanti con default ENT_COMPAT:

Tabella 1. Costanti disponibili per quote_style

Nome della costante	Descrizione
`ENT_COMPAT`	Converte gli apici doppi e lascia inalterati gli apici singoli.
`ENT_QUOTES`	Converte sia gli apici doppi sia gli apici singoli.
`ENT_NOQUOTES`	Lascia entrambi i tipi di apici inalterati.

Per il terzo parametro opzionale, charset, si utilizza come default il set di caratteri ISO-8859-1. Questo parametro indica quale set di caratteri utilizzare per la conversione.

Elenco dei set di caratteri supportati dal PHP 4.3.0 e successivi.

Tabella 2. set di caratteri supportati

Set di caratteri	Alias	Descrizione
ISO-8859-1	ISO8859-1	Western European, Latin-1
ISO-8859-15	ISO8859-15	Western European, Latin-9. Con in più il simbolo dell'Euro e i caratteri francesi e finnici mancanti in Latin-1(ISO-8859-1).
UTF-8		Set ASCII compatibile con il set multi-byte Unicode su 8-bit.
cp866	ibm866, 866	Set di caratteri cirillico specifico del Dos. Supportato dalla 4.3.2.
cp1251	Windows-1251, win-1251, 1251	Set di caratteri cirillico specifico di Windows, Supportato dalla 4.3.2.
cp1252	Windows-1252, 1252	Set di caratteri specifico di Windows per l'Europa occidentale.
KOI8-R	koi8-ru, koi8r	Russo. Supportato dalla 4.3.2.
BIG5	950	Cinese tradizionale, usato principalmente a Taiwan.
GB2312	936	Cinese semplificato, set di caratteri nazionale standard.
BIG5-HKSCS		Big5 con estensioni per Hong Kong, cinese tradizionale.
Shift_JIS	SJIS, 932	Giapponese.
EUC-JP	EUCJP	Giapponese.

Nota: Ogni altro set di caratteri non è riconosciuto e sarà sostituito con con il set ISO-8859-1.

Esempio 1. Decodifica delle entità HTML
<?php $orig = "I'll \"walk\" the <b>dog</b> now"; $a = htmlentities($orig); $b = html_entity_decode($a); echo $a; // I'll "walk" the <b>dog</b> now echo $b; // I'll "walk" the <b>dog</b> now // Per utilizzatori di versioni di PHP antecedenti alla 4.3.0: function unhtmlentities($string) { $trans_tbl = get_html_translation_table(HTML_ENTITIES); $trans_tbl = array_flip($trans_tbl); return strtr($string, $trans_tbl); } $c = unhtmlentities($a); echo $c; // I'll "walk" the <b>dog</b> now ?>

Nota: Ci si può chiedere come mai la sequenza trim(html_entity_decode(' ')); non produca una stringa vuota; questo accade perchè l'intità ' ' non corrisponde al codice ASCII 32 (che verrebbe rimosso da trim()), ma, nella codifica di default ISO-8859-1, corrisponde al carattere ASCII 160 (0xa0).

Vedere anche htmlentities(), htmlspecialchars(), get_html_translation_table(), and urldecode().

htmlentities

(PHP 3, PHP 4, PHP 5)

htmlentities -- Converte tutti i possibili caratteri in entità HTML

Descrizione

string htmlentities ( string string [, int quote_style [, string charset]] )

Questa funzione è identica a htmlspecialchars() tranne che htmlentities() converte tutti i caratteri che hanno una corrispettiva entità HTML.

Come per la funzione htmlspecialchars(), il secondo parametro opzionale quote_style indica cosa occorre fare per gli apici 'singoli' e "doppi". Sono possibili tre scelte indicate da tre costanti con default ENT_COMPAT:

Tabella 1. Costanti disponibili per quote_style

Nome della costante	Descrizione
`ENT_COMPAT`	Converte gli apici doppi e lascia inalterati gli apici singoli.
`ENT_QUOTES`	Converte sia gli apici doppi sia gli apici singoli.
`ENT_NOQUOTES`	Lascia entrambi i tipi di apici inalterati.

Il suupporto per il parametro quote è stato introdotto in PHP 4.0.3.

Come per la funzione htmlspecialchars(), questa ha un terzo parametro charset, opzionale, che definisce quale set di caratteri utilizzare per la conversione. Il supporto per questo parametro è stato aggiunto in PHP 4.1.0. Attualmente per default si utilizza il set ISO-8859-1.

Elenco dei set di caratteri supportati dal PHP 4.3.0 e successivi.

Tabella 2. set di caratteri supportati

Set di caratteri	Alias	Descrizione
ISO-8859-1	ISO8859-1	Western European, Latin-1
ISO-8859-15	ISO8859-15	Western European, Latin-9. Con in più il simbolo dell'Euro e i caratteri francesi e finnici mancanti in Latin-1(ISO-8859-1).
UTF-8		Set ASCII compatibile con il set multi-byte Unicode su 8-bit.
cp866	ibm866, 866	Set di caratteri cirillico specifico del Dos. Supportato dalla 4.3.2.
cp1251	Windows-1251, win-1251, 1251	Set di caratteri cirillico specifico di Windows, Supportato dalla 4.3.2.
cp1252	Windows-1252, 1252	Set di caratteri specifico di Windows per l'Europa occidentale.
KOI8-R	koi8-ru, koi8r	Russo. Supportato dalla 4.3.2.
BIG5	950	Cinese tradizionale, usato principalmente a Taiwan.
GB2312	936	Cinese semplificato, set di caratteri nazionale standard.
BIG5-HKSCS		Big5 con estensioni per Hong Kong, cinese tradizionale.
Shift_JIS	SJIS, 932	Giapponese.
EUC-JP	EUCJP	Giapponese.

Nota: Ogni altro set di caratteri non è riconosciuto e sarà sostituito con con il set ISO-8859-1.

Se si deve esere una decodifica (un giro al contrario) occorre utilizzare la funzione html_entity_decode().

Esempio 1. Un esempio di htmlentities()
<?php $str = "A 'quote' is <b>bold</b>"; // Visualizza: A 'quote' is <b>bold</b> echo htmlentities($str); // Visualizza: A 'quote' is <b>bold</b> echo htmlentities($str, ENT_QUOTES); ?>

Vedere anche html_entity_decode(), get_html_translation_table(), htmlspecialchars(), nl2br() e urlencode().

htmlspecialchars_decode

(PHP 5 >= 5.1.0RC1)

htmlspecialchars_decode -- Convert special HTML entities back to characters

Descrizione

string htmlspecialchars_decode ( string string [, int quote_style] )

This function is the opposite of htmlspecialchars(). It converts special HTML entities back to characters.

The converted entities are: &, " (when ENT_NOQUOTES is not set), ' (when ENT_QUOTES is set), < and >.

Elenco dei parametri

string

The string to decode

quote_style

The quote style. One of the following constants:

Tabella 1. quote_style constants

Constant Name	Description
`ENT_COMPAT`	Will convert double-quotes and leave single-quotes alone (default)
`ENT_QUOTES`	Will convert both double and single quotes
`ENT_NOQUOTES`	Will leave both double and single quotes unconverted

Valori restituiti

Returns the decoded string.

Esempi

Esempio 1. A htmlspecialchars_decode() example
<?php $str = '<p>this -> "</p>'; echo htmlspecialchars_decode($str); // note that here the quotes aren't converted echo htmlspecialchars_decode($str, ENT_NOQUOTES); ?>
Il precedente esempio visualizzerà:
<p>this -> "</p> <p>this -> "</p>

Vedere anche:

htmlspecialchars()

html_entity_decode()

get_html_translation_table()

htmlspecialchars

(PHP 3, PHP 4, PHP 5)

htmlspecialchars -- Converte i caratteri speciali in entità HTML

Descrizione

string htmlspecialchars ( string string [, int quote_style [, string charset]] )

Alcuni caratteri hanno significati particolari in HTML, e, per questo, devono essere rappresentati tramite entità HTML, se devono mantenere il proprio significato. Questa funzione restituisce restituisce una stringa con la conversione di alcuni di questi caratteri; la conversione svolta non è sempre valida nell'ambito della programmazione web. Se occorre l'utilizzo di tutte le entità HTML, utilizzare htmlentities().

Questa funzione è utile nel prevenire la presenza di marcatori HTML negli input utente, tipo nei forum o nei guest book. Il secondo parametro quote_style, opzionale, indica alla funzione come comportarsi con gli apici singoli e doppi. La modalità di default è, ENT_COMPAT; questa modalità è compatibile con il passato e traduce solo gli apici doppi lasciando inalterati gli apici singoli. Se si imposta ENT_QUOTES, entrambi i tipi di apici, singoli e doppi, sono convertiti in entità e, infine, se si utilizza ENT_NOQUOTES ne gli apici singoli ne gli apici doppi sono convertiti in entità.

La conversioni applicate sono:

'&' (e commerciale) diventa '&'
'"' (doppio apice) diventa '"' con ENT_NOQUOTES is not set.
''' (singolo apice) diventa ''' soltanto con l'impostazione di ENT_QUOTES.
'<' (minore) diventa '<'
'>' (maggiore) diventa '>'

Esempio 1. Esempio di uso di htmlspecialchars()

<?php
$new = htmlspecialchars("<a href='test'>Test</a>", ENT_QUOTES);
echo $new; // &lt;a href=&#039;test&#039;&gt;Test&lt;/a&gt;
?>

Occorre notare che questa funzione non converte null'altro oltre ai caratteri elencati in precedenza. Per la conversione di tutte le entità fare riferimento a htmlentities(). Il secondo parametro è stato inserito in PHP 3.0.17 e 4.0.3.

Il terzo parametro charset indica quale set di caratteri utilizzare nella conversione. Il set di caratteri di default è ISO-8859-1. Questo terzo parametro è stato aggiunto in PHP 4.1.0.

Elenco dei set di caratteri supportati dal PHP 4.3.0 e successivi.

Tabella 1. set di caratteri supportati

Set di caratteri	Alias	Descrizione
ISO-8859-1	ISO8859-1	Western European, Latin-1
ISO-8859-15	ISO8859-15	Western European, Latin-9. Con in più il simbolo dell'Euro e i caratteri francesi e finnici mancanti in Latin-1(ISO-8859-1).
UTF-8		Set ASCII compatibile con il set multi-byte Unicode su 8-bit.
cp866	ibm866, 866	Set di caratteri cirillico specifico del Dos. Supportato dalla 4.3.2.
cp1251	Windows-1251, win-1251, 1251	Set di caratteri cirillico specifico di Windows, Supportato dalla 4.3.2.
cp1252	Windows-1252, 1252	Set di caratteri specifico di Windows per l'Europa occidentale.
KOI8-R	koi8-ru, koi8r	Russo. Supportato dalla 4.3.2.
BIG5	950	Cinese tradizionale, usato principalmente a Taiwan.
GB2312	936	Cinese semplificato, set di caratteri nazionale standard.
BIG5-HKSCS		Big5 con estensioni per Hong Kong, cinese tradizionale.
Shift_JIS	SJIS, 932	Giapponese.
EUC-JP	EUCJP	Giapponese.

Nota: Ogni altro set di caratteri non è riconosciuto e sarà sostituito con con il set ISO-8859-1.

Vedere anche get_html_translation_table(), strip_tags(), htmlentities() e nl2br().

implode

(PHP 3, PHP 4, PHP 5)

implode -- Unisce gli elementi di una matrice in una stringa

Descrizione

string implode ( string glue, array pieces )

Restituisce una stringa contenente tutti gli elementi di una matrice nel medesimo ordine, inserendo il parametro glue tra un elemento e l'altro.
Esempio 1. Esempio di uso di implode()
<?php $array = array('lastname', 'email', 'phone'); $comma_separated = implode(",", $array); echo $comma_separated; // lastname,email,phone ?>

Nota: La funzione implode(), per ragioni storiche, può accettare i propri parametri in entrambi gli ordini. Tuttavia per mantenere la consistenza con explode(), ed avere meno confusione, utilizzare i parametri nell'ordine documentato.

Nota: Dal PHP 4.3.0, il parametro glue di implode() è opzionale e come default utilizza una stringa vuota (''). Questo non è l'utilizzo preferenziale di implode(). Si suggerisce di utilizzare sempre il secondo parametro per compatibilità con le vecchie versioni.

Nota: Questa funzione è binary-safe (gestisce correttamente i file binari)

Vedere anche explode() e split().

join

(PHP 3, PHP 4, PHP 5)

join -- Alias di di implode()

Descrizione

This function is an alias of: implode().

levenshtein

(PHP 3 >= 3.0.17, PHP 4 >= 4.0.1, PHP 5)

levenshtein -- Calcola la distanza Levenshtein tra due stringhe

Descrizione

int levenshtein ( string str1, string str2 [, int cost_ins [, int cost_rep, int cost_del]] )

Questa funzione restituisce la distanza Levenshtein tra due stringhe o -1 se uno degli argomenti è più lungo del limite di 255 caratteri.

La distanza Levenshtein è definita come il numero minimo di caratteri da sostituire, inserire o cancellare per trasformare str1 in str2. La complessità dell'algoritmo è O(m*n), dove n e m sono rispettivamente la lunghezza di str1 e di str2 (valore piuttosto buono se confrontato con similar_text(), che è O(max(n,m)**3), ma comunque costoso).

Nella sua versione più semplice la funzione richiede come parametri due stringhe e calcola il numero di caratteri da inserire, sostituire o rimuovere necessari a trasformare str1 in str2.

La seconda variante utilizza tre parametri addizionali che definiscono il costo delle operazioni di inserimento, sostituzione e di cancellazione. Questa versione è più generale e adattabile della precedente, ma non è altrettanto efficiente.

Esempio 1. Esempio di uso di levenshtein()
<?php // input parola errata $input = 'carrrot'; // matrice di parole con cui verificare $words = array('apple','pineapple','banana','orange', 'radish','carrot','pea','bean','potato'); // non ancora trovata la distanza più breve $shortest = -1; // loop su tutte le parole per trovare la più simile foreach ($words as $word) { // calcola la distanza tra la parola di input // e la corrente $lev = levenshtein($input, $word); // è la parola esatta? if ($lev == 0) { // la più simile è questa $closest = $word; $shortest = 0; // esce dal loop, l'abbiamo trovata break; } // se la distanza è inferiore rispetto alla precendete più corta // o non ne abbiamo ancora trovata una if ($lev <= $shortest || $shortest < 0) { // imposta la parola più simile e la distanza più breve $closest = $word; $shortest = $lev; } } echo "Input word: $input\n"; if ($shortest == 0) { echo "Exact match found: $closest\n"; } else { echo "Did you mean: $closest?\n"; } ?>
Il precedente esempio visualizzerà:
Input word: carrrot Did you mean: carrot?

Vedere anche soundex(), similar_text() e metaphone().

localeconv

(PHP 4 >= 4.0.5, PHP 5)

localeconv -- Ottiene informazioni sul formato numerico

Descrizione

array localeconv ( void )

La funzione restituisce un array associativo contenente le configurazioni locali per il formato numerico e monetario.

La funzione localeconv() restituisce i dati in base alle configurazioni locali come impostate da setlocale(). L'array associativo restituito contiene i seguenti campi:

Elemento Descrizione

decimal_point Carattere per il punto decimale

thousands_sep Separatore delle migliaia

grouping Array contenente i gruppi numerici

int_curr_symbol Simbolo internazionale della divisa (i.e. USD)

currency_symbol Simbolo della divisa locale (i.e. $)

mon_decimal_point Carattere per il punto decimale nella moneta

mon_thousands_sep Separatore delle migliaia nella moneta

mon_grouping Array contenente i gruppi monetari

positive_sign Segno per i valori positivi

negative_sign Segno per i valori negativi

int_frac_digits Numero di caratteri frazionali internazionali

frac_digits Numero di caratteri frazionali locali

p_cs_precedes TRUE se il simbolo della divisa precede i valori positivi, FALSE se segue tali valori

p_sep_by_space TRUE se uno spazio separa il simbolo della divisa dai valori positivi FALSE in caso contrario

n_cs_precedes TRUE se il simbolo della divisa precede i valori negativi, FALSE se segue tali valori

n_sep_by_space TRUE se uno spazio separa il simbolo della divisa dai valori negativi, FALSE in caso contrario

p_sign_posn

0	Parentesi attorno alla quantità ed al simbolo della divisa
1	Il segno precede la quantità ed al simbolo della divisa
2	Il segno segue la quantità ed al simbolo della divisa
3	Il segno precede immediatamente il simbolo della divisa
4	Il segno segue immediatamente il simbolo della divisa

n_sign_posn

0	Parentesi attorno alla quantità ed al simbolo della divisa
1	Il segno precede la quantità ed al simbolo della divisa
2	Il segno segue la quantità ed al simbolo della divisa
3	Il segno precede immediatamente il simbolo della divisa
4	Il segno segue immediatamente il simbolo della divisa

I campi di raggruppamento contengono matrici che definiscono il modo con cui i numeri dovrebbero essere raggruppati. Ad esempio, i campi di raggruppamento per il formato en_US, contengono due elementi con i valori 3 e 3. L'indice più alto indica quanto è distinta il gruppo di sinistra. Se un elemento della matrice è uguale a CHAR_MAX, non vi sono più gruppi. Se nella matrice vi è un elemento a 0, occorre utilizzare l'elemento precedente.

Esempio 1. Esempio di uso di localeconv()

<?php
setlocale(LC_ALL, "en_US");

$locale_info = localeconv();

echo "<pre>\n";
echo "--------------------------------------------\n";
echo "  Informazioni sulla configurazione monetaria locale:  \n";
echo "--------------------------------------------\n\n";

echo "int_curr_symbol:   {$locale_info["int_curr_symbol"]}\n";
echo "currency_symbol:   {$locale_info["currency_symbol"]}\n";
echo "mon_decimal_point: {$locale_info["mon_decimal_point"]}\n";
echo "mon_thousands_sep: {$locale_info["mon_thousands_sep"]}\n";
echo "positive_sign:     {$locale_info["positive_sign"]}\n";
echo "negative_sign:     {$locale_info["negative_sign"]}\n";
echo "int_frac_digits:   {$locale_info["int_frac_digits"]}\n";
echo "frac_digits:       {$locale_info["frac_digits"]}\n";
echo "p_cs_precedes:     {$locale_info["p_cs_precedes"]}\n";
echo "p_sep_by_space:    {$locale_info["p_sep_by_space"]}\n";
echo "n_cs_precedes:     {$locale_info["n_cs_precedes"]}\n";
echo "n_sep_by_space:    {$locale_info["n_sep_by_space"]}\n";
echo "p_sign_posn:       {$locale_info["p_sign_posn"]}\n";
echo "n_sign_posn:       {$locale_info["n_sign_posn"]}\n";
echo "</pre>\n";
?>

E' presente una costante, CHAR_MAX, per gli utilizzi descritti in precedenza.

Vedere anche setlocale().

ltrim

(PHP 3, PHP 4, PHP 5)

ltrim -- Rimuove gli spazi (o altri caratteri) dall'inizio di una stringa

Descrizione

string ltrim ( string str [, string charlist] )

Nota: Il secondo parametro è stato aggiunto nella versione 4.1.0 di PHP.

Questa funzione restituisce la stringa str a cui sono stati rimossi gli spazi iniziali. Senza la specifica del secondo parametro ltrim() rimuoverà i seguenti caratteri:

" " (ASCII 32 (0x20)), spazio ordinario.
"\t" (ASCII 9 (0x09)), tab.
"\n" (ASCII 10 (0x0A)), newline (line feed).
"\r" (ASCII 13 (0x0D)), carriage return.
"\0" (ASCII 0 (0x00)), il byte NUL.
"\x0B" (ASCII 11 (0x0B)), il tab verticale.

Si può anche specificare i caratteri che si desidera rimuovere, indicandoli nel parametro charlist. Quest'ultimo è costituito da un semplice elenco di caratteri da rimuovere. Con .. si può specificare un range di caratteri.

Esempio 1. Esempio di uso di ltrim()

<?php

$text = "\t\tThese are a few words :) ...  ";
$trimmed = ltrim($text);
// $trimmed = "These are a few words :) ...  "
$trimmed = ltrim($text, " \t.");
// $trimmed = "These are a few words :) ...  "
$clean = ltrim($binary, "\x00..\x1F");
// rimuove i caratteri di controllo ASCII dall'inizio di $binary 
// (from 0 to 31 inclusive)

?>

Vedere anche trim() and rtrim().

md5_file

(PHP 4 >= 4.2.0, PHP 5)

md5_file -- Calcola l'hash md5 del file dato

Descrizione

string md5_file ( string filename [, bool raw_output] )

Calcola l'hash md5 del file filename utilizzando l' RSA Data Security, Inc. MD5 Message-Digest Algorithm, e lo restituisce. L'hash prodotto è un numero esadecimale di 32 caratteri. Se il secondo parametro raw_output è impostato a TRUE, il valore md5 è restituito nel formato binario raw con una lunghezza di 16 caratteri.

Nota: Il parametro opzionale raw_output è stato aggiunto in PHP 5.0.0, e come default vale FALSE

Questa funzione ha il medesimo scopo dell'utilità di linea di comando md5sum.

Vedere anche md5(), crc32() e sha1_file().

md5

(PHP 3, PHP 4, PHP 5)

md5 -- Calcola il valore md5 di una stringa

Descrizione

string md5 ( string str [, bool raw_output] )

Calcola il valore md5 della stringa str utilizzando il RSA Data Security, Inc. MD5 Message-Digest Algorithm, e restituisce tale valore. L'hash prodotto è un numero esadecimale di 32 caratteri. Se il secondo parametro raw_output è impostato a TRUE, il valore md5 è restituito nel formato binario raw con una lunghezza di 16 caratteri.

Nota: Il parametro opzionale raw_output è stato aggiunto in PHP 5.0.0, e come default vale FALSE

Esempio 1. Esempio di uso di md5()
<?php $str = 'apple'; if (md5($str) === '1f3870be274f6c49b3e31a0c6728957f') { echo "Would you like a green or red apple?"; exit; } ?>

Vedere anche crc32(), md5_file() e sha1().

metaphone

(PHP 4, PHP 5)

metaphone -- Calcola la chiave metaphone di una stringa

Descrizione

string metaphone ( string str [, int phones] )

Calcola la chiave metaphone di str.

In modo simile a soundex() la funzione crea la medesima chiave per parole con il medesimo suono. Questa funzione è più accurata che soundex() poiché conosce le regole di base della pronuncia inglese. Le chiavi metaphone generate hanno lunghezza variabile.

La chiave Metaphone è stata sviluppata da Lawrence Philips <lphilips at verity dot com>. Viene descritta in ["Practical Algorithms for Programmers", Binstock & Rex, Addison Wesley, 1995].

money_format

(PHP 4 >= 4.3.0, PHP 5)

money_format -- Formattazione di un numero come stringa monetaria

Descrizione

string money_format ( string format, float number )

money_format() restituisce una versione formattata di number. Questa funzione è un'interfaccia alla funzione C strfmon(), con la differenza che questa funzione converte un solo numero alla volta.

Nota: La funzione money_format() esiste solo se il sistema suppporta strfmon. Ad esempio, Windows non lo supporta perciò la funzione money_format() non è definita su Windows.

LA specifica del formato consiste nella seguente sequenza:

un carattere %
un flag opzionale flags
la lunghezza del campo, opzionale
la precisione a sinistra, opzionale
la precisione a destra, opzionale
un carattere di conversione, obbligatorio

Flag. Si possono utilizzare uno o più dei seguenti flag:

=f: Il carattere = seguito da un singolo carattere (singolo byte) f è utilizzato come carattere di riempimento numerico. Il carattere di default è lo spazio.
^: Disabilita l'utilizzo del raggruppamento dei caratetrei (come definito nelle impostazioni locali).
+ oppure (: Specifica lo stile di formattazione per i numeri positivi e negativi. Se si utilizza +, sarà utilizzato l'equivalente valore locale per + e -. Se si utilizza (, i valori negativi saranno racchiusi tra parentesi. Se non si da specifica, il default è +.
!: Sopprime il simbolo della moneta nella stringa di output.
-: Se presente, rende tutti i campi giustificati a sinistra (riempiti a a destra), il default prevede i campi allineati a destra (riempiti a sinistra).

Dimensioni del campo.

w: Una stringa numerica che specifica la lunghezza minima del campo. Il campo sarà allineato a destra a meno di non avere impostato il flag -. Il valore di default è 0 (zero).

Precisione a sinistra.

#n

Sono attesi un numero massimo di (n) numeri a sinistra del carattere decimale (es. il punto decimale). Solitamente si utilizza per mantenere allineato l'output nella medesima colonna, utilizzando il carattere di riempimento, se il numero delle cifre è inferiore a n. Se il numero delle cifre è superiore a n, questa specifica viene ignorata.

Se il raggruppamento delle cifre non è soppresso tramite ^, saranno inseriti i separatori di raggruppamento prima dei caratteri di riempimento (se presenti). I separatori di gruppo non saranno applicati ai caratteri di riempimento, anche se il carattere di riempimento è un numero.

Per garantire l'allineamento, ogni carattere che, nella stringa formattata, appare prima o dopo il numero, tipo il simbolo della moneta o il segno, viene riempito con gli spazi necessari affinché la corrispondente stringa risultante da un valore positivo o negativo abbia la medesima lunghezza.

Precisione di destra .

.p: Un punto seguito da un numero di cifre (p) dopo il carattere decimale. Se il valore di p è 0 (zero), il carattere decimale e le cifre alla sua destra saranno omesse. Se non vi è indicazione della precisione a destra, il default sarà preso della impostazioni locali. L'importo sarà arrontondato alle cifre decimali richieste prima di essere formattato.

Caratteri di conversione .

i: Il numero sarà formattato in base alle impostazioni internazionali locali (es. le impostazioni locali USA: USD 1,234.56).
n: Il numero sarà formattato in base alle locali impostazioni nazionali di moneta (es. per de_DE: DM1.234,56).
%: Restituisce il carattere %.

Nota: La categoria LC_MONETARY delle impostazioni locali influisce sul comportamento di questa funzione. Utilizzare setlocale() per impostare il default appropriato prima di utilizzare questa funzione.
I caratteri prima e dopo la stringa di formattazione saranno restituiti immutati.

Esempio 1. Esempio di uso di money_format()
Per illustrare il funzionamento della funzione utilizzeremo diversi formati di impostazioni locali.
<?php $number = 1234.56; // stampa nel formato internazionale per l'impostazione en_US setlocale(LC_MONETARY, 'en_US'); echo money_format('%i', $number) . "\n"; // USD 1,234.56 // Fromato italiano con 2 cifre decimali` setlocale(LC_MONETARY, 'it_IT'); echo money_format('%.2n', $number) . "\n"; // L. 1.234,56 // Numeri negativi $number = -1234.5672; // Formato nazionale US, Utilizzo di () per i numeri negativi // e 10 cifre di precisione a sinistra setlocale(LC_MONETARY, 'en_US'); echo money_format('%(#10n', $number) . "\n"; // ($ 1,234.57) // Simile al precente con 2 cifre di precisione a destra // e '*' come carattere di riempimento echo money_format('%=*(#10.2n', $number) . "\n"; // ($********1,234.57) // Giustificazione a sinistra, con 14 posizioni di lunghezza, 8 cifre di // precisione a sinistra, 2 di precisione a destra, senza carattere di raggruppamento // e utilizzando l'impostazione locale de_DE. setlocale(LC_MONETARY, 'de_DE'); echo money_format('%=*^-14#8.2i', 1234.56) . "\n"; // DEM 1234,56**** // Qualche carattere prima e dopo la specifica di formattazione setlocale(LC_MONETARY, 'en_GB'); $fmt = 'The final value is %i (after a 10%% discount)'; echo money_format($fmt, 1234.56) . "\n"; // The final value is GBP 1,234.56 (after a 10% discount) ?>

Vedere anche setlocale(), number_format(),sprintf(), printf() e sscanf().

nl_langinfo

(PHP 4 >= 4.1.0, PHP 5)

nl_langinfo -- Ricava informazioni sulla lingua e le impostazioni locali

Descrizione

string nl_langinfo ( int item )

La funzione nl_langinfo() viene utilizzata per accedere agli elementi delle impostazioni locali. Diversamente da localeconv(), che restituisce tutti gli elementi, nl_langinfo() permette di scegliere l'elemento specifico.

Se il parametro item non è valido, la funzione restituisce FALSE.

Il parametro item può essere un numero intero od il nome della costante indicante l'elemento. Di seguito viene riportata la lista dei nomi per item con le rispettive descrizioni. Alcune di quest costanti possono non essere definite in alcune impostazioni locali.

Tabella 1. Costanti di nl_langinfo

Costante	Descrizione
Costanti per la categoria LC_TIME
ABDAY_(1-7)	Nome abbreviato dell'n-esimo giorno della settimana.
DAY_(1-7)	Nome dell'n-esimo giorno della settimana (DAY_1 = domenica).
ABMON_(1-12)	Nome abbreviato dell'n-esimo mese dell'anno.
MON_(1-12)	Nome dell'n-esimo mese dell'anno.
AM_STR	Stringa per ante meridiano.
PM_STR	Stringa per pomeridiano.
D_T_FMT	Stringa di formato che può essere usata con strftime() per rappresentare la data e l'ora.
D_FMT	Stringa di formato che può essere usata con strftime() per rappresentare la data.
T_FMT	Stringa di formato che può essere usata con strftime() per rappresentare l'ora.
T_FMT_AMPM	Stringa di formato che può essere usata con strftime() per rappresentare la data e l'ora nel formato a 12 ore con ante/post meridiano.
ERA	Era alternativa.
ERA_YEAR	Formato dell'anno nell'era alternativa.
ERA_D_T_FMT	Formato di data e ora nell'era alternativa (la stringa può essere usata con strftime()).
ERA_D_FMT	Formato della data nell'era alternativa (la stringa può essere usata con strftime()).
ERA_T_FMT	Formato dell'ora nell'era alternativa (la stringa può essere usata con strftime()).
Costanti per la categoria LC_MONETARY
INT_CURR_SYMBOL	Simbolo internazionale della divisa.
CURRENCY_SYMBOL	Simobolo locale della moneta.
CRNCYSTR	Stesso valore di CURRENCY_SYMBOL.
MON_DECIMAL_POINT	Carattere separatore delle cifre decimali.
MON_THOUSANDS_SEP	Separatore delle migliaia (gruppi di tre cifre).
MON_GROUPING	Come l'elemento di raggruppamento.
POSITIVE_SIGN	Segno per i valori positivi.
NEGATIVE_SIGN	Segno per i valori negativi.
INT_FRAC_DIGITS	Numero di cifre frazionarie internazionale.
FRAC_DIGITS	Numero di cifre frazionarie locale.
P_CS_PRECEDES	Resituisce 1 se CURRENCY_SYMBOL precede un valore positivo.
P_SEP_BY_SPACE	Resituisce 1 se uno spazio separa CURRENCY_SYMBOL da un valore positivo.
N_CS_PRECEDES	Resituisce 1 se CURRENCY_SYMBOL precede un valore negativo.
N_SEP_BY_SPACE	Resituisce 1 se uno spazio separa CURRENCY_SYMBOL da un valore negativo.
P_SIGN_POSN	Restituisce 0 se le parentesi circondano il valore ed il simbolo di moneta. Restituisce 1 se il segno precede il valore ed il simbolo di moneta. Restituisce 2 se il segno segue il valore ed il simbolo di moneta. Restituisce 3 se il segno precede immediatamente il simbolo di moneta. Restituisce 4 se il segno segue immediatamente il simbolo di moneta.
N_SIGN_POSN
Costanti per la categoria LC_NUMERIC
DECIMAL_POINT	Carattere separatore delle cifre decimali.
RADIXCHAR	Come DECIMAL_POINT.
THOUSANDS_SEP	Separatore delle migliaia (gruppi di tre cifre).
THOUSEP	Come THOUSANDS_SEP.
GROUPING
Costanti per la categoria LC_MESSAGES
YESEXPR	Stringa regex per il riconoscimento di 'si'.
NOEXPR	Stringa regex per il riconoscimento di 'no'.
YESSTR	Testo da visualizzare per 'si'.
NOSTR	Testo da visualizzare per 'no'.
Costanti per la categoria LC_CTYPE
CODESET	Restituisce una stringa con il nome della codifica dei caratteri.

Nota: Questa funzione non è implementata su piattaforme Windows

Vedere anche setlocale() e localeconv().

nl2br

(PHP 3, PHP 4, PHP 5)

nl2br -- Inserisce il tag HTML di 'a capo' prima di tutti i caratteri di 'a capo' della stringa

Descrizione

string nl2br ( string string )

Restituisce la stringa string con '<br />' inserito prima di tutti i newline.

Nota: A partire dal PHP 4.0.5, nl2br() è conforme a XHTML. Tutte le versioni precedenti alla 4.0.5 restituiscono la string con '<br>' invece di '<br />' inserito prima degli 'a capo'.

Esempio 1. Esempio di uso di nl2br()
<?php echo nl2br("foo isn't\n bar"); ?>
this will output :
foo isn't<br /> bar

Vedere anche htmlspecialchars(), htmlentities(), wordwrap() e str_replace().

number_format

(PHP 3, PHP 4, PHP 5)

number_format -- Formatta un numero con i grupppi delle migliaia

Descrizione

string number_format ( float number [, int decimals [, string dec_point, string thousands_sep]] )

La funzione number_format() restituisce una versione formattata di number. Questa funzione accetta uno, due, o quattro parametri (non tre).

Se si specifica soltanto un parametro, il number sarà formattato senza decimali, ma con la virgola (",") per suddividere le migliaia.

Se sono specdificati due parametri, il number sarà formattato con tante cifre decimali quanto indicato in decimals, precedute dal punto ("."), e con la virgola (",") come separatore delle migliaia.

Se sono indicati tutti i quattro parametri, il number sarà formattato con decimals cifre decimali, identificate dal carattere dec_point anziché dal punto (".") e con thousands_sep, invece della virgola (",") come separatore delle migliaia.

Sarà utilizzato solo il primo carattere di thousands_sep. Ad esempio, se si indica foo come thousands_sep per il numero 1000, la funzione number_format() restituirà 1f000.

Esempio 1. Esempio di uso di number_format()
Ad esempio, la notazione francese solitamente utilizza due decimali, la virgola (',') come separatore decimale, e lo spazio (' ') come separatore delle migliaia. Questo può essere ottenuto con:
<?php $number = 1234.56; // Notazione inglese (default) $english_format_number = number_format($number); // 1,235 // Notazione francese $nombre_format_francais = number_format($number, 2, ',', ' '); // 1 234,56 $number = 1234.5678; // notazione inglese senza separatore delle migliaia $english_format_number = number_format($number, 2, '.', ''); // 1234.57 ?>

Vedere anche sprintf(), printf() e sscanf().

ord

(PHP 3, PHP 4, PHP 5)

ord -- Restituisce il valore ASCII di un carattere

Descrizione

int ord ( string string )

Restituisce il valore ASCII del primo carattere di string. Questa è la funzione complementare di chr().
Esempio 1. Esempio di uso di ord()
<?php $str = "\n"; if (ord($str) == 10) { echo "The first character of \$str is a line feed.\n"; } ?>

Qui si può reperire la tabella ASCII: http://www.asciitable.com.

Vedere anche chr().

parse_str

(PHP 3, PHP 4, PHP 5)

parse_str -- Suddivide una stringa in variabili

Descrizione

void parse_str ( string str [, array arr] )

Suddivide la stringa str come se fosse una stringa di query passata via URL ed imposta le variabili con visibilità locale. Se si indica il secondo parametro arr, la variabili sono memorizzate come elementi della matrice arr.

Nota: Il supporto per il secondo parametro, opzionale, è stato aggiunto in PHP 4.0.3.

Nota: Per avere la QUERY_STRING corrente occorre utilizzare la variabile $_SERVER['QUERY_STRING']. Inoltre è opportuno leggere la sezione sulle variabili esterne al PHP.

Nota: L'impostazione magic_quotes_gpc influisce sull'output di questa funzione, poichè parse_str() utilizza lo stesso meccanismo che usa il PHP per compilare le variabili $_GET, $_POST, ecc.

Esempio 1. Esempio di uso di parse_str()
<?php $str = "first=value&arr[]=foo+bar&arr[]=baz"; parse_str($str); echo $first; // value echo $arr[0]; // foo bar echo $arr[1]; // baz parse_str($str, $output); echo $output['first']; // value echo $output['arr'][0]; // foo bar echo $output['arr'][1]; // baz ?>

Vedere anche parse_url(), pathinfo(), get_magic_quotes_gpc() e urldecode().

print

(PHP 3, PHP 4, PHP 5)

print -- Visualizza una stringa

Descrizione

int print ( string arg )

Visualizza arg. Restituisce sempre 1,

In realtà print() non è una funzione (è un costrutto del linguaggio) pertanto non sono richieste le parentesi per la lista degli argomenti.

Esempio 1. Esempio di uso di print()
<?php print("Hello World"); print "print() also works without parentheses."; print "This spans multiple lines. The newlines will be output as well"; print "This spans\nmultiple lines. The newlines will be\noutput as well."; print "escaping characters is done \"Like this\"."; // Si possono usare variabili all'interno di istruzioni print $foo = "foobar"; $bar = "barbaz"; print "foo is $foo"; // foo is foobar // Si possono usare le matrici $bar = array("value" => "foo"); print "this is {$bar['value']} !"; // this is foo ! // Utilizzando l'apice singolo sarà visualizzato il nome della variabile e non il contenuto print 'foo is $foo'; // foo is $foo // Se non si usa altri caratteri, si può semplicemente visualizzare il contenuto della variabile print $foo; // foobar print <<<END This uses the "here document" syntax to output multiple lines with $variable interpolation. Note that the here document terminator must appear on a line with just a semicolon no extra whitespace! END; ?>

Per breve discussione tra print() e echo(), vedere la pagina di FAQTs Knowledge Base Article: http://www.faqts.com/knowledge_base/view.phtml/aid/1/fid/40

Nota: Poichè questo è un costrutto del linguaggio e non una funzione, non può essere chiamato con le variabili funzione

Vedere anche echo(), printf(), e flush().

printf

(PHP 3, PHP 4, PHP 5)

printf -- Visualizza una stringa formattata

Descrizione

int printf ( string format [, mixed args [, mixed ...]] )

Produce un output formattato secondo le specifiche del parametro format, che viene descritto nella documentazione di sprintf().

Restituisce la lunghezza della stringa visualizzata.

Vedere anche print(), sprintf(), vprintf(), sscanf(), fscanf() e flush().

quoted_printable_decode

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

quoted_printable_decode -- Converte una stringa 'quoted-printable' in una stringa a 8 bit

Descrizione

string quoted_printable_decode ( string str )

Questa funzione restituisce una stringa a 8 bit corrispondente alla codifica della stringa 'quoted-printable' ( in base a RFC2045, sezione 6.7, e non RFC2821, sezione 4.5.2, punti addizionali non sono rimossi dall'inizio della linea). Questa funzione è simile a imap_qprint(), tranne che quest'ultima richiede il modulo IMAP per essere utilizzata.

quotemeta

(PHP 3, PHP 4, PHP 5)

quotemeta -- Quota i meta caratteri

Descrizione

string quotemeta ( string str )

Restituisce una versione di str con il carattere backslash (\) davanti ai seguenti caratteri:
. \ + * ? [ ^ ] ( $ )

Nota: Questa funzione è binary-safe (gestisce correttamente i file binari)

Vedere anche addslashes(), htmlentities(), htmlspecialchars(), nl2br() e stripslashes().

rtrim

(PHP 3, PHP 4, PHP 5)

rtrim -- Rimuove gli spazi (ed altri caratteri) dalla fine della stringa

Descrizione

string rtrim ( string str [, string charlist] )

Nota: Il secondo parametro è stato aggiunto nella versione 4.1.0 di PHP.

Questa funzione restituisce la stringa str a cui sono stati rimossi gli spazi finali. Senza la specifica del secondo parametro rtrim() rimuoverà i seguenti caratteri:

" " (ASCII 32 (0x20)), spazio ordinario.
"\t" (ASCII 9 (0x09)), tab.
"\n" (ASCII 10 (0x0A)), newline (line feed).
"\r" (ASCII 13 (0x0D)), carriage return.
"\0" (ASCII 0 (0x00)), il byte NUL.
"\x0B" (ASCII 11 (0x0B)), il tab verticale.

Esempio 1. Esempio di uso di rtrim()

<?php

$text = "\t\tThese are a few words :) ...  ";
$trimmed = rtrim($text);
// $trimmed = "\t\tThese are a few words :) ..."
$trimmed = rtrim($text, " \t.");
// $trimmed = "\t\tThese are a few words :)"
$clean = rtrim($binary, "\x00..\x1F");
// rimuove i caratteri di controllo ASCII dalla fine di $binary 
// (from 0 to 31 inclusive)

?>

Vedere anche trim() e ltrim().

setlocale

(PHP 3, PHP 4, PHP 5)

setlocale -- Imposta i parametri di localizzazione

Descrizione

string setlocale ( mixed category, string locale [, string ...] )

string setlocale ( mixed category, array locale )

Il parametro category è una costante (o stringa) che indica la categoria di parametri coinvolta nelle impostazioni locali:

LC_ALL la somma di tutte le seguenti categorie
LC_COLLATE per i confronti di stringhe, vedere strcoll()
LC_CTYPE per la classificazione dei caratteri e le conversioni, ad esempio strtoupper()
LC_MONETARY per localeconv()
LC_NUMERIC per il separatore decimale (vedere anche localeconv())
LC_TIMEper la formattazione di data e orario con strftime()

Nota: Dalla versione 4.2.0 di PHP il passaggio di category come stringa è deprecato; piuttosto utilizzare le precedenti costanti. Passare quelle costanti come stringa (all'interno di apici) darà come risultato un warning.

Se il parametro locale è NULL oppure una stringa vuota "", i nomi locali saranno impostati dai valori delle omonime variabili d'ambiente, oppure da "LANG".

Se il parametro locale vale "0", le impostazioni localizzate non vengono toccate, ma vengono restituiti i valori correnti.

Se il parametro locale è una matrice oppure è seguito da parametri addizionali, allora si tenterà di impostare ciascun elemento, o parametro, fino a quando non si ha successo. Questo è utile se l'impostazione locale è nota sotto differenti nomi in sistemi differenti oppure per prevedere più casistiche qualora alcune non fossero disponibili.

Nota: Il passaggio di molteplici impostazioni non è possibile prima di PHP 4.3.0.

La funzione restituisce le nuove impostazioni locali, oppure FALSE se la funzionalità di localizzazione non è implementata sul sistema, se l'impostazione richiesta non esiste, oppure se il nome della categoria non è valida. Un nome di categoria non valido genera anche un warning. I nomi delle categoria possono essere trovati nella RFC 1766 e ISO 639. Differenti sistemi hanno differenti schemi di denominazione delle impostazioni locali.

Nota: Il valore restituito da setlocale() dipende dal sistema su cui gira il PHP. La funzione restituisce fedelmente quello che la funzione di sistema restituisce.

Suggerimento: Gli utenti di Windows potranno trovare informazioni utili per il parametro locale sul sito MSDN di Microsoft. Le stringhe di linguaggio supportate possono essere trovate in http://msdn.microsoft.com/library/default.asp?url=/library/en-us/vclib/html/_crt_language_strings.asp e le stringhe identificanti i paesi/regioni alla pagina http://msdn.microsoft.com/library/default.asp?url=/library/en-us/vclib/html/_crt_country_strings.asp. I sistemi Windows supportano la codifica a tre lettere ISO 3166-Alpha-3 per identificare i paesi/regioni ISO 3166-Alpha-3, tale codifica può essere reperita nel sito . .

Esempio 1. Esempi di uso di setlocale()
<?php /* Impostazioni locali in tedesco */ setlocale(LC_ALL, 'nl_NL'); /* Visualizza: vrijdag 22 december 1978 */ echo strftime("%A %e %B %Y", mktime(0, 0, 0, 12, 22, 1978)); /* tenta i differenti nomi possibili per le impostazioni tedesche, dal PHP 4.3.0 */ $loc_de = setlocale(LC_ALL, 'de_DE@euro', 'de_DE', 'de', 'ge'); echo "Preferred locale for german on this system is '$loc_de'"; ?>

Esempio 2. Esempio di uso di setlocale() perWindows
<?php /* Impostazioni locali in tedesco */ setlocale(LC_ALL, 'nld_nld'); /* Visualizza: vrijdag 22 december 1978 */ echo strftime("%A %d %B %Y", mktime(0, 0, 0, 12, 22, 1978)); /* tenta i differenti nomi possibili per le impostazioni tedesche, dal PHP 4.3.0 */ $loc_de = setlocale(LC_ALL, 'de_DE@euro', 'de_DE', 'deu_deu'); echo "Preferred locale for german on this system is '$loc_de'"; ?>

sha1_file

(PHP 4 >= 4.3.0, PHP 5)

sha1_file -- Calcola l'hash sha1 di un file

Descrizione

string sha1_file ( string filename [, bool raw_output] )

Calcola l'hash sha1 di filename usando il US Secure Hash Algorithm 1, e restituisce l'hash. L'hash è un numero esadecimale di 40 caratteri.

Elenco dei parametri

filename: Il nome del file
raw_output: Quando è impostato a TRUE, l'hash sha1 è restituito in formato binario con una lunghezza di 20 caratteri. Per default vale FALSE.

Valori restituiti

Restituisce una stringa se ha successo, FALSE negli altri casi.

Log delle modifiche

Versione	Descrizione
5.0.0	Aggiunto il parametro `raw_output`.
5.1.0	Modificata la funzione per utilizzare lr API streams. Ciò significa che si può utlizzare la funzione con i vari warppers, tipo `sha1_file('http://example.com/..')`

Vedere anche:

sha1()

md5_file()

crc32()

sha1

(PHP 4 >= 4.3.0, PHP 5)

sha1 -- Calcola l'hash sha1 di una stringa

Descrizione

string sha1 ( string str [, bool raw_output] )

Calcola l'hash sha1 di str usando il US Secure Hash Algorithm 1, e restituisce l'hash. L'hash è un numero esadecimale di 40 caratteri. Se il parametro opzionale raw_output è impostato a TRUE, allora l'hash sha1 è restituito in formato binario con una lunghezza di 20 caratteri.

Nota: Il parametro opzionale raw_output è stato aggiunto in PHP 5.0.0 ed ha come default FALSE

Esempio 1. Esempio di uso di sha1()
<?php $str = 'apple'; if (sha1($str) === 'd0be2dc421be4fcd0172e5afceea3970e2f3d940') { echo "Would you like a green or red apple?"; exit; } ?>

Vedere anche sha1_file(), crc32() e md5()

similar_text

(PHP 3 >= 3.0.7, PHP 4, PHP 5)

similar_text -- Calcola la similitudine tra due stringhe

Descrizione

int similar_text ( string first, string second [, float &percent] )

Questa funzione calcola la similitudine tra due stringhe come descritto in Oliver [1993]. Attenzione che questa implementazione non utilizza lo stack come nel psuedo codice di Oliver, ma utilizza chiamate ricorsive che possono o non possono velocizzare l'intero processo. Occorre anche rilevare che la complessità di questo algoritmo è O(N**3) dove N è la lunghezza della stringa più lunga.

Passando per riferimento il terzo argomento, similar_text() la funzione calcolerà la similitudine in percentuale. La funzione restituisce il numero di caratteri corrispondenti in entrambe le stringhe.

Vedere anche levenshtein() e soundex().

soundex

(PHP 3, PHP 4, PHP 5)

soundex -- Calcola la chiave soundex di una data stringa

Descrizione

string soundex ( string str )

Calcola la chiave soundex di str.

Le chiavi soundex hanno la caratteristica di essere simili per parole con pronuncia similare, e pertanto possono essere utilizzate per semplificare le ricerche in archivi nei casi in cui si conosce la pronuncia ma non la sillabazione. Questa funzione soundex restituisce una stringa di 4 caratteri di cui il primo è una lettera.

Questa particolare funzione soundex è stata descritta da Donald Knuth in "The Art Of Computer Programming, vol. 3: Sorting And Searching", Addison-Wesley (1973), pp. 391-392.

Esempio 1. Esempio di uso di Soundex
<?php soundex("Euler") == soundex("Ellery"); // E460 soundex("Gauss") == soundex("Ghosh"); // G200 soundex("Hilbert") == soundex("Heilbronn"); // H416 soundex("Knuth") == soundex("Kant"); // K530 soundex("Lloyd") == soundex("Ladd"); // L300 soundex("Lukasiewicz") == soundex("Lissajous"); // L222 ?>

Vedere anche levenshtein(), metaphone() e similar_text().

sprintf

(PHP 3, PHP 4, PHP 5)

sprintf -- Restituisce una stringa formattata

Descrizione

string sprintf ( string format [, mixed args [, mixed ...]] )

La funzione restituisce una stringa formattata in base al parametro format.

La stringa di formato è composta da 0 o più direttive: i caratteri ordinari (escluso il %) sono copiati direttamente nel risultato, mentre le specifiche di conversione, scaricano il proprio parametro. Queste note si applicano alle funzioni fprintf(), sprintf() e printf().

Ciascun parametro di conversione consiste nel segno percento (%), seguito da uno più dei seguenti elementi nell'ordine si ha:

Un parametro opzionale di specifica del segno che forza la presenza del segno (- oppure +) in caso di numero. Per default, si usa soltanto il segno - se il numero è negativo. Questo parametro forza i numeri positiva ad avere il segno +, ed è stato aggiunto in PHP 4.3.0.
Un parametro opzionale per la specifica del riempimento che indica quale carattere sarà utilizzato per completare la stringa risultante in modo da raggiungere la dimensione richiesta. Questo può essere uno spazio oppure uno 0 (il carattere zero). Per default si completa con spazi. Un carattere di riempimento alternativo può essere indicato anteponendo a questo l'apice singolo ('). Vedere gli esempi seguenti.
Un parametro opzionale per la specifica dell'allineamento che indica se la stringa risultante debba essere giustificata a destra o a sinistra. Per default le stringhe sono giustificate a destra; il carattere - forza la giustificazione a sinistra.
Un parametro numerico opzionale per la specifica della dimensione che indica di quanti caratteri (come minimo) debba essere lunga la stringa.
Un parametro opzionale per indicare la precisione per indicare quante cifre decimali debbano essere visualizzate per i numeri in virgola mobile. Quando si usa questo parametro in una stringa si impone come una sorta di punto di cutoff, esso imposta un limite alla lunghezza della stringa.

Una specifica di tipo che indica il tipo di dati dell'argomento. I possibili tipi sono:

% - il carattere percento. Nessun argomento è richiesto.

b - l'argomento è trattato come un intero e sarà presentato come numero binario.

c - l'argomento è trattato come un intero e sarà presentato come carattere ASCII del valore corrispondente.

d - l'argomento è trattato come un intero e sarà presentato come un numero decimale con segno.

e - l'argomento è reso con notazione scientifica (ad esempio 1.2e+2).

u - l'argomento è trattato come un intero e sarà presentato come un numero decimale senza segno.

f - l'argomento è trattato come un float e sarà presentato come un numero in virgola mobile (influenzato dalle impostazioni locali).

F - l'argomento è trattato come un numero float, e sarà presentato come un numero in virgola mobile (non influenzato dalle impostazioni locali). Disponibile da PHP 4.3.10 e PHP 5.0.3.

o - l'argomento è trattato come un intero e sarà presentato come un numero ottale.

s - l'argomento sarà trattato e presentato come una stringa.

x - l'argomento sarà trattato come un intero e presentato in forma esadecimale (con le lettere in minuscolo).

X - l'argomento è trattato come un intero e sarà presentato come un numero esadecimale (con le lettere maiuscole).

A partire dal PHP 4.0.6 la stringa di formato supporta lo scambio dei parametri. Eccone un esempio:
Esempio 1. Scambio dei parametri
<?php $format = "There are %d monkeys in the %s"; printf($format, $num, $location); ?>
Questo esempio visualizza: "There are 5 monkeys in the tree". Ma supponiamo di volere creare una stringa di formato in file a parte, perchè vogliamo rendere la procedura internazionale; e pertanto riscriviamo l'esempio come:
Esempio 2. Scambio dei parametri
<?php $format = "The %s contains %d monkeys"; printf($format, $num, $location); ?>
Ora abbiamo un problema. L'ordine dei segnaposto nella stringa di formato non coincide con l'ordine dei parametri. Si vorrebbe potere lasciare inalterato il codice e potere indicare a quale parametro si riferisce il segnaposto. Ciò può essere fatto modificando la stringa di formato come:
Esempio 3. Scambio dei parametri
<?php $format = "The %2\$s contains %1\$d monkeys"; printf($format, $num, $location); ?>
Un beneficio aggiuntivo è che si possono ripetere i segnaposto senza dovere ripetere i parametri. Ad esempio:
Esempio 4. Scambio di parametri
<?php $format = "The %2\$s contains %1\$d monkeys. That's a nice %2\$s full of %1\$d monkeys."; printf($format, $num, $location); ?>

Vedere anche printf(), sscanf(), fscanf(), vsprintf() e number_format().

Esempi

Esempio 5. Esempi di uso di printf()

<?php
$n =  43951789;
$u = -43951789;
$c = 65; // ASCII 65 is 'A'

// attenzione che i doppi %%, visualizzano il carattere '%' 
printf("%%b = '%b'\n", $n); // rappresentazione binaria
printf("%%c = '%c'\n", $c); // visualizza un carattere ASCII, coma la funzione chr()
printf("%%d = '%d'\n", $n); // rappresentazione di un intero standard
printf("%%e = '%e'\n", $n); // notazione scientifica
printf("%%u = '%u'\n", $n); // rappresentazione di un intero positivo privo di segno
printf("%%u = '%u'\n", $u); // rappresentazione di un intero negativo privo di segno
printf("%%f = '%f'\n", $n); // rappresentazine in virgola mobile
printf("%%o = '%o'\n", $n); // rappresentazione ottale
printf("%%s = '%s'\n", $n); // stringa
printf("%%x = '%x'\n", $n); // rappresentazione esadecimale (minuscolo)
printf("%%X = '%X'\n", $n); // rappresentazione esadecimale (maiuscolo)
printf("%%+d = '%+d'\n", $n); // indicazione del segno su un intero positivo
printf("%%+d = '%+d'\n", $u); // indicazione del segno su un intero negativo
?>

L'output di questo programma sarà:

%b = '10100111101010011010101101'
%c = 'A'
%d = '43951789'
%e = '4.39518e+7'
%u = '43951789'
%u = '4251015507'
%f = '43951789.000000'
%o = '247523255'
%s = '43951789'
%x = '29ea6ad'
%X = '29EA6AD'
%+d = '+43951789'
%+d = '-43951789'

Esempio 6. printf(): specifiche di stringa

<?php
$s = 'monkey';
$t = 'many monkeys';

printf("[%s]\n",      $s); // output standard di stringa
printf("[%10s]\n",    $s); // accostamento a destra con spazi
printf("[%-10s]\n",   $s); // accostamento a sinistra con spazi
printf("[%010s]\n",   $s); // completamento con zero funziona anche con le stringhe
printf("[%'#10s]\n",  $s); // utilizza il carattere di riempimento  '#'
printf("[%10.10s]\n", $t); // accostamento a sinistra con taglio a 10 caratteri
?>

L'output di questo programma sarà:

[monkey]
[    monkey]
[monkey    ]
[0000monkey]
[####monkey]
[many monke]

Esempio 7. sprintf(): interi completati con zeri

<?php
$isodate = sprintf("%04d-%02d-%02d", $year, $month, $day);
?>

Esempio 8. sprintf(): formattazione della moneta

<?php
$money1 = 68.75;
$money2 = 54.35;
$money = $money1 + $money2;
// echo $money visualizzerà "123.1";
$formatted = sprintf("%01.2f", $money);
// echo $formatted visualizzerà "123.10"
?>

Esempio 9. sprintf(): notazione scientifica

<?php
$number = 362525200;

echo sprintf("%.3e", $number); // visualizza 3.63e+8
?>

sscanf

(PHP 4 >= 4.0.1, PHP 5)

sscanf -- Analizza l'input da una string in base al formato

Descrizione

mixed sscanf ( string str, string format [, mixed &...] )

La funzione sscanf() è la versione di input di printf(). sscanf() legge dalla stringa str e ne interpreta il contenuto basandosi sul parametro format, che viene descritto nella documentazione di sprintf(). Se vengono passati soltanto due parametri, i valori ricavati sono restituiti in una matrice. Altrimenti, se viene fornito il terzo parametro, la funzione restituire il numero dei valori assegnati. Il terzo parametro deve essere passato per riferimento.

Qualsiasi tipo di spazio nella stringa di formato identifica il corrispondente spazio nella stringa di input. Ciò significa che anche i tab \t nella stringa di formato possono identificare un carattere di spazio nella stringa di input.

Esempio 1. Esempio di uso di sscanf()
<?php // getting the serial number $serial = sscanf("SN/2350001", "SN/%d"); // and the date of manufacturing $mandate = "January 01 2000"; list($month, $day, $year) = sscanf($mandate, "%s %d %d"); echo "Item $serial was manufactured on: $year-" . substr($month, 0, 3) . "-$day\n"; ?>
Se viene fornito il terzo parametro, la funzione restituire il numero dei valori assegnati.
Esempio 2. sscanf() - utilizzo del parametro opzionale
<?php // get author info and generate DocBook entry $auth = "24\tLewis Carroll"; $n = sscanf($auth, "%d\t%s %s", $id, $first, $last); echo "<author id='$id'> <firstname>$first</firstname> <surname>$last</surname> </author>\n"; ?>

Vedere anche fscanf(), printf() e sprintf().

str_ireplace

(PHP 5)

str_ireplace -- Versione insensibile alle miuscole/minuscole di str_replace()

Descrizione

mixed str_ireplace ( mixed search, mixed replace, mixed subject [, int &count] )

Questa funzione restituisce una stringa od una matrice con tutte le occorrenze di search in subject (non distinguendo tra maiuscole e minuscole) sostituite con il valore replace Se non occorrono particolari regole di sostituzione si dovrebbe utilizzare questa funzione anziché eregi_replace() o preg_replace() con il parametro i.

Se il parametro subject è una matrice, allora la ricerca e la sostituzione viene eseguita su ogni elemento di subject, ed il valore restituito è pure quello una matrice.

Se search e replace sono matrici, allora str_ireplace() prende i valori da ciascuna matrice e li utilizza per fare la ricerca e la sostituzione in subject. Se replace ha meno valori di search, allora si utilizza una stringa vuota per sostituire i valori mancanti. Se search è una matrice e replace è una stringa; allora questa stringa viene utilizzata per sostituire ogni valore di search.

Esempio 1. Esempio di uso di str_ireplace()
<?php $bodytag = str_ireplace("%body%", "black", "<body text=%BODY%>"); ?>

Questa funzione è sicura con i dati binari.

Nota: Dal PHP 5.0.0 il numero dei testi trovati e sostituiti sarà restituito in count che deve essere passato per riferimento. Prima del PHP 5.0.0 questo parametro non è disponibile.

Vedere anche: str_replace(), ereg_replace(), preg_replace() e strtr().

str_pad

(PHP 4 >= 4.0.1, PHP 5)

str_pad -- Riempie una stringa con un'altra stringa portando la prima ad una lunghezza pre-determinata

Descrizione

string str_pad ( string input, int pad_length [, string pad_string [, int pad_type]] )

Questa funzione restituisce la stringa input riempita per una data lunghezza a sinistra, a destra, o in entrambi i lati. Se il parametro opzionale pad_string non viene passato, l' input viene completato con spazi, altrimenti viene completato con i caratteri di pad_string fino al limite.

Il parametro pad_type, opzionale, può valere STR_PAD_RIGHT, STR_PAD_LEFT, oppure STR_PAD_BOTH. Se non si indica pad_type lo si assume pari a STR_PAD_RIGHT.

Se il valore di pad_length è negativo oppure minore della stringa di input, non si ha nessun completamento.

Esempio 1. Esempio di uso di str_pad()
<?php $input = "Alien"; echo str_pad($input, 10); // produces "Alien " echo str_pad($input, 10, "-=", STR_PAD_LEFT); // produces "-=-=-Alien" echo str_pad($input, 10, "_", STR_PAD_BOTH); // produces "__Alien___" echo str_pad($input, 6 , "___"); // produces "Alien_" ?>

Nota: Il parametro pad_string può essere troncato se il numero di caratteri necessari al completamento non può essere diviso per la lunghezza di pad_string.

str_repeat

(PHP 4, PHP 5)

str_repeat -- Ripete una stringa

Descrizione

string str_repeat ( string input, int multiplier )

Restituisce il parametro input_str ripetuto tante volte quanto indicato in multiplier. multiplier deve essere maggiore o uguale a 0. Se multiplier è impostato a zero, la funzione restituisce una stringa vuota.

Esempio 1. Esempio di uso di str_repeat()

<?php
echo str_repeat("-=", 10);
?>

Il precedente esempio visualizzerà:

-=-=-=-=-=-=-=-=-=-=

Vedere anche for, str_pad() e substr_count().

str_replace

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

str_replace -- Sostituisce tutte le occorrenze della stringa cercata con la stringa di sostituzione

Descrizione

mixed str_replace ( mixed search, mixed replace, mixed subject [, int &count] )

Questa funzione restituisce una stringa, od una matrice, con tutte le occorrenze di search nella stringa subject sostituite con il valore del parametro replace. Se non occorrono particolari capacità di sostituzione (tipo le espressioni regolari), si dovrebbe utilizzare questa funzione invece di ereg_replace() o preg_replace().

Dal PHP 4.0.5, ogni parametro di str_replace() può essere una matrice.

Avvertimento

Nelle versioni di PHP antecedenti la 4.3.3 esisteva un errore quando si utilizzano le matrici per search e replace che faceva ignorare gli indici vuoti di search avanzando il puntatore interno di replace, questo è stato corretto dal PHP 4.3.3, ogni script che si basava su questo errore, per potere simulare il comportamento originale, dovrebbe rimuovere gli elementi vuoti prima di richiamare questa funzione.

Se subject è una matrice, allora la ricerca e la sostituzione sono eseguite su ogni elemento di subject, ed il valore restituito è pure una matrice.

Se search e replace sono matrici, allora str_replace() prende i valori da ciascuna matrice e li usa per svolgere la ricerca e la sostituzione in subject. Se replace ha meno valori di search, allora si utilizzeranno delle stringhe vuote per completare i rimanenti valori da sostituire. Se search è una matrice e replace è una stringa, allora questa stringa di sostituzione sarà utilizzata per ogni valore di search. Il contrario non avrebbe senso.

Esempio 1. Esempi di uso di str_replace()
<?php // Provides: <body text='black'> $bodytag = str_replace("%body%", "black", "<body text='%body%'>"); // Provides: Hll Wrld f PHP $vowels = array("a", "e", "i", "o", "u", "A", "E", "I", "O", "U"); $onlyconsonants = str_replace($vowels, "", "Hello World of PHP"); // Provides: You should eat pizza, beer, and ice cream every day $phrase = "You should eat fruits, vegetables, and fiber every day."; $healthy = array("fruits", "vegetables", "fiber"); $yummy = array("pizza", "beer", "ice cream"); $newphrase = str_replace($healthy, $yummy, $phrase); // Use of the count parameter is available as of PHP 5.0.0 $str = str_replace("ll", "", "good golly miss molly!", $count); echo $count; // 2 ?>

Nota: Questa funzione è binary-safe (gestisce correttamente i file binari)

Nota: Dal PHP 5.0.0 il numero di stringhe trovate e e sostituite, sarà restituito nel parametro, passato per riferimento, count. Nelle versioni antecedenti al PHP 5.0.0 questo parametro non è disponibile.

Esempio 1. Esempi di uso di str_split()
<?php $str = "Hello Friend"; $arr1 = str_split($str); $arr2 = str_split($str, 3); print_r($arr1); print_r($arr2); ?>
L'output potrà essere:
Array ( [0] => H [1] => e [2] => l [3] => l [4] => o [5] => [6] => F [7] => r [8] => i [9] => e [10] => n [11] => d ) Array ( [0] => Hel [1] => lo [2] => Fri [3] => end )

Esempio 2. Esempi relativi a str_split()
<?php $str = "Hello Friend"; echo $str{0}; // H echo $str{8}; // i // Creates: array('H','e','l','l','o',' ','F','r','i','e','n','d') $arr1 = preg_split('//', $str, -1, PREG_SPLIT_NO_EMPTY); ?>

Vedere anche: chunk_split(), preg_split(), split(), count_chars(), str_word_count() e for.

str_word_count

(PHP 4 >= 4.3.0, PHP 5)

str_word_count -- Restituisce informazioni sulle parole utilizzate in una stringa

Descrizione

mixed str_word_count ( string string [, int format [, string charlist]] )

Conta il numero di parole presenti in string. Se non viene indicato il parametro opzionale format, allora la funzione restituirà un intero indicante il numero di parole trovate. Nel caso in cui sia specificato format, la funzione restituisce una matrice il cui contenuto dipende dal parametro format. I possibili valori per format ed i rispettivi output sono elencati di seguito.

Per gli scopi di questa funzione 'parola' è definita come testo dipendente dalle impostazioni locali, contenente caratteri alfabetici, che può contenere, ma non cominciare, con i caratteri "'" and "-".

Elenco dei parametri

string

La stringa

format

Indica il tipo di valore restituito dalla funzione. Le attuali impostazioni ammesse per il parametro sono:

0 - restituisce il numero di parole trovate
1 - restituisce una matrice contenente tutte le parole trovate all'interno di string.
2 - restituisce una matrice associativa, in cui le chiavi sono la posizione numerica della parola in string ed il valore è la parola stessa.

charlist

Lista di caratteri addizionali da considerare come 'parole'

Valori restituiti

Restituisce un intero od una matrice in base al valore di format.

Log delle modifiche

Versione	Descrizione
5.1.0	Aggiunto il parametro `charlist`

Esempi

Esempio 1. Esempio di uso di str_word_count()
<?php $str = "Hello fri3nd, you're looking good today!"; print_r(str_word_count($str, 1)); print_r(str_word_count($str, 2)); print_r(str_word_count($str, 1, 'àáãç3')); echo str_word_count($str); ?>
Il precedente esempio visualizzerà:
Array ( [0] => Hello [1] => fri [2] => nd [3] => you're [4] => looking [5] => good [6] => today ) Array ( [0] => Hello [6] => fri [10] => nd [14] => you're [29] => looking [46] => good [51] => today ) Array ( [0] => Hello [1] => fri3nd [2] => you're [3] => looking [4] => good [5] => today ) 7

Vedere anche:

explode()

preg_split()

split()

count_chars()

substr_count()

strcasecmp

(PHP 3 >= 3.0.2, PHP 4, PHP 5)

strcasecmp -- Confronto non sensibile alle maiuscole e sicuro con i dati binari

Descrizione

int strcasecmp ( string str1, string str2 )

Restituisce < 0 se str1 è minore di str2; > 0 se str1 è maggiore di str2, e 0 se sono uguali.
Esempio 1. Esempio di uso di strcasecmp()
<?php $var1 = "Hello"; $var2 = "hello"; if (strcasecmp($var1, $var2) == 0) { echo '$var1 is equal to $var2 in a case-insensitive string comparison'; } ?>

Vedere anche ereg(), strcmp(), substr(), stristr(), strncasecmp() e strstr().

strchr

(PHP 3, PHP 4, PHP 5)

strchr -- Alias di strstr()

Descrizione

This function is an alias of: strstr().

strcmp

(PHP 3, PHP 4, PHP 5)

strcmp -- Confronto tra stringhe affidabile con dati binari

Descrizione

Questa funzione tenga di restituire una stringa priva dei tag HTML e PHP partendo dalla stringa str. La funzione utilizza la stessa macchina a stati di rimozione dei tag utilizzata per la funzione fgetss().

Si può utilizzare il secondo parametro, opzionale, per indicare quale tag ignorare.

Nota: allowable_tags è stato aggiunto in PHP 3.0.13 e PHP 4.0b3.
Dal PHP 4.3.0, sono rimossi anche i commenti HTML. Questo comportamento è da programma e non può essere modificato tramite allowable_tags.

Avvertimento

Poiché strip_tags() non valida il testo HTML, tag parziali, o interrotti possono portare alla rimozione di più testo di quanto atteso.

Avvertimento

Questa funzione non modifica alcun attributo sui tag che sono abilitati tramite allowable_tags, incluso lo style e l'attributo onmouseover che possono essere sfruttati da utenti malevoli quando pubblicano testi che saranno visualizzati da altri utenti.

Esempio 1. Esempio di uso di strip_tags()
<?php $text = '<p>Test paragraph.</p> Other text'; echo strip_tags($text); echo "\n"; // allow <p> echo strip_tags($text, '<p>'); ?>
Il precedente esempio visualizzerà:
Test paragraph. Other text <p>Test paragraph.</p> Other text

La funzione strip_tags() è sicura con i contenuti binari dal PHP 5.0.0

Vedere anche htmlspecialchars().

stripcslashes

(PHP 4, PHP 5)

stripcslashes -- Rimuove gli slash aggiunti con addcslashes()

Descrizione

string stripcslashes ( string str )

Rimuove i backslash da una stringa. Riconosce i caratteri C \n, \r ..., le rappresentazioni ottali e esadecimali.

Vedere anche addcslashes().

stripos

(PHP 5)

stripos -- Trova la prima occorrenza in una stringa senza distinzione tra maiuscole e minuscole

Descrizione

int stripos ( string haystack, string needle [, int offset] )

Restituisce la posizione numerica della prima occorrenza di needle nella stringa haystack. Differentemente da strpos(), stripos() non distingue tra maiuscole e minuscole.

Occorre rilevare che needle può essere una stringa di uno o più caratteri.

Se needle non viene trovato, stripos() restituirà boolean FALSE.

Avvertimento

Esempio 1. Esempi di uso di stripos()
<?php $findme = 'a'; $mystring1 = 'xyz'; $mystring2 = 'ABC'; $pos1 = stripos($mystring1, $findme); $pos2 = stripos($mystring2, $findme); // No, 'a' non è certamente in 'xyz' if ($pos1 === false) { echo "The string '$findme' was not found in the string '$mystring1'"; } // Notate l'uso di ===. Semplicemente == non avrebbe funzionato come atteso // perchè la posizione di 'a' è nel carattere 0 (il primo). if ($pos2 !== false) { echo "We found '$findme' in '$mystring2' at position $pos2"; } ?>

Se needle non è una stringa, sarà convertito in un intero e utilizzato come valore ordinale di un carattere.

Il parametro opzionale offset permette di indicare da quale carattere di haystack iniziare la ricerca. La posizione restituita sarà relativa all'inizio di haystack.

Nota: Questa funzione è binary-safe (gestisce correttamente i file binari)

Vedere anche strpos(), strrpos(), strrchr(), substr(), stristr(), strstr(), strripos() e str_ireplace().

stripslashes

(PHP 3, PHP 4, PHP 5)

stripslashes -- Rimuove gli slash aggiunti con addslashes()

Descrizione

string stripslashes ( string str )

Rimuove i backslash da una stringa. (\' diventa ' e così via.) I doppi backslash (\\) sono ridotti ad un singolo backslash (\).

Un esempio di uso di stripslashes() è dato dall'opzione PHP magic_quotes_gpc che, quando è impostata a on (come è per default), e non siinseriscono questi dati in una procedura (tipo in un database) che richiede il carattere di escape. Ad esempio, se si visualizza dati da un form HTML.

Esempio 1. Esempio di uso di stripslashes()
<?php $str = "Is your name O\'reilly?"; // Outputs: Is your name O'reilly? echo stripslashes($str); ?>

Nota: La funzione stripslashes() non è ricorsiva Se si desidera utilizzare questa funzione su una matrice multi-dimensionale, occorre utilizzare una funzione ricorsiva.

Esempio 2. Esempio di utilizzo di stripslashes() su una matrice
<?php function stripslashes_deep($value) { $value = is_array($value) ? array_map('stripslashes_deep', $value) : stripslashes($value); return $value; } // Example $array = array("f\\'oo", "b\\'ar", array("fo\\'o", "b\\'ar")); $array = stripslashes_deep($array); // Output print_r($array); ?>
Il precedente esempio visualizzerà:
Array ( [0] => f'oo [1] => b'ar [2] => Array ( [0] => fo'o [1] => b'ar ) )

Per maggiori dettagli su "magic quotes", vedere get_magic_quotes_gpc().

Vedere anche addslashes() e get_magic_quotes_gpc().

stristr

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

stristr -- Versione insensibile alle maiuscole/minuscole di strstr()

Descrizione

string stristr ( string haystack, string needle )

Restituisce il contenuto di haystack dalla prima occorrenza di needle fino alla fine. needle e haystack sono esaminati senza distinguere tra lettere maiuscole e minuscole.

Se needle non viene trovato, la funzione restituisce FALSE.

Se needle non è una stringa, viene convertito in un intero e si utilizza il valore ordinale del carattere.

Esempio 1. Esempio di uso di stristr()
<?php $email = 'USER@EXAMPLE.com'; echo stristr($email, 'e'); // outputs ER@EXAMPLE.com ?>

Esempio 2. Verifica se una stringa esiste o meno
<?php $string = 'Hello World!'; if(stristr($string, 'earth') === FALSE) { echo '"earth" not found in string'; } // outputs: "earth" not found in string ?>

Esempio 3. Utilizzo di un dato non stringa da cercare
<?php $string = 'APPLE'; echo stristr($string, 97); // 97 = lowercase a // outputs: APPLE ?>

Nota: Questa funzione è binary-safe (gestisce correttamente i file binari)

Il precedente codice visualizzerà:

Standard string comparison
Array
(
    [0] => img1.png
    [1] => img10.png
    [2] => img12.png
    [3] => img2.png
)

Natural order string comparison
Array
(
    [0] => img1.png
    [1] => img2.png
    [2] => img10.png
    [3] => img12.png
)

Per maggiori informazioni vedere: Martin Pool's Natural Order String Comparison page.

Al pari delle altre funzioni di confronto tra stringhe, questa restituisce < 0 se str1 è minore di str2; > 0 se str1 è maggiore di str2, e 0 se sono uguali.

Nota questo confronto distingue tra lettere maiuscole e minuscole.

Vedere anche ereg(), strcasecmp(), substr(), stristr(), strcmp(), strncmp(), strncasecmp(), strnatcasecmp(), strstr(), natsort() e natcasesort().

strncasecmp

(PHP 4 >= 4.0.2, PHP 5)

strncasecmp -- Confronto sicuro con i testi binari, insensibile alle lettere maiuscole/minuscole sui primi n caratteri

Descrizione

int strncasecmp ( string str1, string str2, int len )

Questa funzione è simile a strcasecmp(), con la differenza che si può indicare il numero dei caratteri (len) per ciascuna stringa che possono essere utilizzati per il confronto.

Restituisce < 0 if str1 se è minore di str2; > 0 se str1 è maggiore di str2, e 0 se sono uguali.

Vedere anche ereg(), strcasecmp(), strcmp(), substr(), stristr() e strstr().

strncmp

(PHP 4, PHP 5)

strncmp -- Confronto tra stringhe sui primi n caratteri, sicuro con i dati binari

Descrizione

int strncmp ( string str1, string str2, int len )

Questa funzione è simile a strcmp(), con la differenza che si può specificare il limite superiore del numero di caratteri (len) per ciascuna stringa, da utilizzare per il confronto.

Restituisce < 0 se str1 è minore di str2; > 0 se str1 è maggiore di str2, e 0 se sono uguali.

Nota: questo confronto distingue tra lettere minuscole e maiuscole.

Vedere anche ereg(), strncasecmp(), strcasecmp(), substr(), stristr(), strcmp() e strstr().

strpbrk

(PHP 5)

strpbrk -- Ricerca in una stringa uno qualsiasi dei caratteri di un dato set

Descrizione

string strpbrk ( string haystack, string char_list )

strpbrk() cerca nella stringa haystack i caratteri indicati in char_list, e restituisce una stringa a partire dal carattere trovato (oppure FALSE se non ve ne sono).

Nota: char_list distingue tra maiuscole e minuscole.

Esempio 1. Esempio di uso di strpbrk()
<?php $text = 'This is a Simple text.'; // visualizza "is is a Simple text." because 'i' is matched first echo strpbrk($text, 'mi'); // visualizza "Simple text." because chars are case sensitive echo strpbrk($text, 'S'); ?>

strpos

(PHP 3, PHP 4, PHP 5)

strpos -- Trova la posizione della prima occorrenza di una stringa

Descrizione

int strpos ( string haystack, mixed needle [, int offset] )

Restituisce la posizione numerica della prima occorrenza di needle nella stringa haystack. Differentemente rispetto a strrpos(), questa funzione considera tutta la stringa needle, e, quindi, cercherà tutta la stringa.

Se needle non viene trovato strpos() restituirà boolean FALSE.

Avvertimento

Nota: Questa funzione è binary-safe (gestisce correttamente i file binari)

Esempio 1. Esempio di uso di strpos()
<?php $mystring = 'abc'; $findme = 'a'; $pos = strpos($mystring, $findme); // Notate l'uso di ===. Il == non avrebbe risposto come atteso // poichè la posizione di 'a' è nel primo carattere. if ($pos === false) { echo "The string '$findme' was not found in the string '$mystring'"; } else { echo "The string '$findme' was found in the string '$mystring'"; echo " and exists at position $pos"; } // Ricerca di un carattere ignorando qualsiasi cosa prima di offset $newstring = 'abcdef abcdef'; $pos = strpos($newstring, 'a', 1); // $pos = 7, not 0 ?>

Se needle non è una stringa, viene convertito in un intero e utilizzato come valore ordinale di un carattere.

Il parametro opzionale offset permette di indicare da quale carattere in haystack iniziare la ricerca. La posizione restituita è, comunque, relativa all'inizio di haystack.

Vedere anche strrpos(), stripos(), strripos(), strrchr(), substr(), stristr() e strstr().

strrchr

(PHP 3, PHP 4, PHP 5)

strrchr -- Trova l'ultima occorrenza di un carattere in una stringa

Descrizione

string strrchr ( string haystack, string needle )

Questa funzione restituisce la porzione di haystack che inizia dall'ultima occorrenza di needle e finisce al termine di haystack.

Restituisce FALSE se needle non viene trovato.

Se needle contiene più di un carattere, in PHP 4 si utilizza solo il primo. Questo comportamento è differente rispetto a strchr().

Se needle non è una stringa, viene convertito in un intero e utilizzato come valore ordinale di un carattere.
Esempio 1. Esempio di uso di strrchr()
<?php // L'ultima directory in $PATH $dir = substr(strrchr($PATH, ":"), 1); // ottiene qualsiasi cosa dopo l'ultimo newline $text = "Line 1\nLine 2\nLine 3"; $last = substr(strrchr($text, 10), 1 ); ?>

strrchr() è affidabile con i dati binari dal PHP 4.3.0

Vedere anche strstr(), substr() e stristr().

strrev

(PHP 3, PHP 4, PHP 5)

strrev -- Inverte una stringa

Descrizione

string strrev ( string string )

Restituisce la stringa string invertita.
Esempio 1. Invertire una stringa con strrev()
<?php echo strrev("Hello world!"); // outputs "!dlrow olleH" ?>

strripos

(PHP 5)

strripos -- Trova la posizione dell'ultima occorrenza di una stringa in un'altra indipendentemente dalle lettere minuscole/maiusole

Descrizione

int strripos ( string haystack, string needle [, int offset] )

Restituisce la posizione numerica dell'ultima occorrenza di needle nella stringa haystack. Differentemente da strrpos(), strripos() non distingue tra lettere maiuscole minuscole. Attenzione che le posizioni della stringa partono da 0 e non da 1.

Notare anche che needle può essere una stringa di uno o più caratteri.

Se needle non è reperito, la funzione restituisce FALSE.

Avvertimento

Esempio 1. Un semplice esempio di strripos()
<?php $haystack = 'ababcd'; $needle = 'aB'; $pos = strripos($haystack, $needle); if ($pos === false) { echo "Sorry, we did not find ($needle) in ($haystack)"; } else { echo "Congratulations!\n"; echo "We found the last ($needle) in ($haystack) at position ($pos)"; } ?>
Output:
Congratulations! We found the last (aB) in (ababcd) at position (2)

Il parametro offset può indicare la posizione da cui cominciare la ricerca nella stringa.

Offset negativi inizieranno la ricerca alla posizione offset dall'inizio della stringa.

Vedere anche: strrpos(), strrchr(), substr(), stripos() e stristr().

strrpos

(PHP 3, PHP 4, PHP 5)

strrpos -- Trova la posizione dell'ultima occorrenza di un carattere in una stringa

Descrizione

int strrpos ( string haystack, string needle [, int offset] )

Restituisce la posizione numerica dell'ultima occorrenza di needle nella stringa haystack. Fare attenzione che needle, in PHP 4, può essere solo un singolo carattere. Se si passa una stringa, verrà utilizzato solo il primo carattere.

Se needle non viene trovato, la funzione restituisce FALSE.

Si può facilmente confondere i valori restituiti "per carattere alla posizione 0" e per "carattere non trovato". Ecco come rilevare la differenza:

<?php

// in PHP 4.0b3 e successivi:
$pos = strrpos($mystring, "b");
if ($pos === false) { // note: three equal signs
    // not found...
}

// nelle versioni precedenti alla 4.0b3:
$pos = strrpos($mystring, "b");
if (is_bool($pos) && !$pos) {
    // not found...
}
?>

Se needle non è una stringa, viene convertito in un intero, e usato come valore ordinale di un carattere.

Nota: Dal PHP 5.0.0 offset può essere indicato per indicare di iniziare la ricerca nella stringa da una posizione di caratteri arbitraria. Valori negativi fermeranno la ricerca ad un punto arbitrario prima della fine della stringa.

Nota: Il parametro needle può essere una stringa di uno o più caratteri a partire dal PHP 5.0.0.

Vedere anche: strpos(), strripos(), strrchr(), substr(), stristr() e strstr().

strspn

(PHP 3 >= 3.0.3, PHP 4, PHP 5)

strspn -- Trova la lunghezza di un testo che corrisponde alla maschera data

Descrizione

int strspn ( string str1, string str2 [, int start [, int length]] )

Restituisce la lunghezza di un segmento di str1 che contiene completamente i caratteri presenti in str2.

Il seguente codice:

<?php
$var = strspn("42 is the answer, what is the question ...", "1234567890");
?>

assegnerà 2 a $var, poichè la stringa "42" è il più lungo segmento contenente i caratteri da "1234567890".

Dal PHP 4.3.0, strspn() accetta altri due parametri interi opzionali: start che può essere usato per indicare la posizione di inizio da cui cercare, e length per indicare la lunghezza della stringa da esaminare.

<?php
echo strspn("foo", "o", 1, 2); // 2
?>

Nota: Questa funzione è binary-safe (gestisce correttamente i file binari)

Vedere anche strcspn().

strstr

(PHP 3, PHP 4, PHP 5)

strstr -- Trova la prima occorrenza di una stringa

Descrizione

string strstr ( string haystack, string needle )

Restituisce la parte della stringa haystack dalla prima occorrenza di needle fino alla fine di haystack.

Se non si trova needle, restituisce FALSE.

Se needle non è una stringa, il parametro viene convertito in un intero e utilizzato come valore ordinale di un carattere.

Nota: Questa funzione distingue tra maiuscole e minuscole. Per una versione che non abbia questa distinzione guardare stristr().

Esempio 1. Esempio di uso di strstr()
<?php $email = 'user@example.com'; $domain = strstr($email, '@'); echo $domain; // prints @example.com ?>

Nota: Se si desidera soltanto determinare se una particolare stringa è presente in haystack, utilizzare la più veloce e meno costosa in termini di memoria strpos().

strstr() è sicura con i dati binari dal PHP 4.3.0

Vedere anche: ereg(), preg_match(), stristr(), strpos(), strrchr() e substr().

strtok

(PHP 3, PHP 4, PHP 5)

strtok -- Suddivide una stringa in token

Descrizione

string strtok ( string str, string token )

strtok() suddivide la stringa(str) in piccole stringhe (tokens), in cui ciascun token è delimitato dal carattere indicato in token. Perciò, se si ha la stringa "This is an example string" la si può dividere nelle singole parole utilizzando come separatore lo spazio.
Esempio 1. Esempio di uso di strtok()
<?php $string = "This is\tan example\nstring"; /* Use tab and newline as tokenizing characters as well */ $tok = strtok($string, " \n\t"); while ($tok !== false) { echo "Word=$tok<br />"; $tok = strtok(" \n\t"); } ?>

Soltanto la prima chiamata a strtok() utilizza il parametro stringa. Ogni chiamata successiva richiede solo il carattere da utilizzare, poichè la funzione tiene traccia di dove è arrivata nella stringa corrente. Per ripartire da capo o iniziare con una nuova stringa ri-chiamare strtok() con il parametro stringa. Nota: si possono mettere più caratteri come separatori di stringhe. Il testo iniziale verrà suddiviso quando viene trovato uno qualsiasi di questi caratteri. Attenzione che soltanto la prima chiamata di strtok userà l'argomento stringa.

Il comportamento su segmenti vuoti è cambiato dal PHP 4.1.0. La vecchia versione restituiva una stringa vuota, mentre la nuova, più correttamente, salta quella parte di stringa:
Esempio 2. Vecchio comportamento di strtok()
<?php $first_token = strtok('/something', '/'); $second_token = strtok('/'); var_dump($first_token, $second_token); ?>
Output:
string(0) "" string(9) "something"

Esempio 3. Nuovo comportamento di strtok()
<?php $first_token = strtok('/something', '/'); $second_token = strtok('/'); var_dump($first_token, $second_token); ?>
Output:
string(9) "something" bool(false)

Avvertimento

Vedere anche: split() e explode().

strtolower

(PHP 3, PHP 4, PHP 5)

strtolower -- Converte in minuscolo una stringa

Descrizione

string strtolower ( string str )

La funzione restituisce la stringa string con tutti i caratteri alfabetici convertiti in minuscolo.

Nota: i caratteri 'alfabetici' sono determinati in base alle impostazioni locali. Ciò significa, ad esempio, che nelle impostazioni locali di default del "C", il carattere umlaut-A (Ä) non sarà convertito.

Esempio 1. Esempio di uso di strtolower()

<?php
$str = "Mary Had A Little Lamb and She LOVED It So";
$str = strtolower($str);
echo $str; // Prints mary had a little lamb and she loved it so
?>

Nota: Questa funzione è binary-safe (gestisce correttamente i file binari)

Vedere anche: strtoupper(), ucfirst(), ucwords() e mb_strtolower().

strtoupper

(PHP 3, PHP 4, PHP 5)

strtoupper -- Converte in maiuscolo una stringa

Descrizione

string strtoupper ( string string )

Restituisce la stringa string con i caratteri alfabetici convertiti in maiuscolo.

Esempio 1. Esempio di uso di strtoupper()

<?php
$str = "Mary Had A Little Lamb and She LOVED It So";
$str = strtoupper($str);
echo $str; // Prints MARY HAD A LITTLE LAMB AND SHE LOVED IT SO
?>

Nota: Questa funzione è binary-safe (gestisce correttamente i file binari)

Vedere anche: strtolower(), ucfirst(), ucwords() e mb_strtoupper().

strtr

(PHP 3, PHP 4, PHP 5)

strtr -- Traduce certi caratteri

Descrizione

string strtr ( string str, string from, string to )

string strtr ( string str, array replace_pairs )

Questa funzione restituisce una copia di str, traducendo tutti i caratteri di from al corrispondente carattere indicato in to.

Se from e to hanno lunghezze differenti, i caratteri in più presenti nella stringa più lunga saranno ignorati.
Esempio 1. Esempio di uso di strtr()
<?php $addr = strtr($addr, "äåö", "aao"); ?>

strtr() può essere eseguita con solo due argomenti. Se viene chiamata con due parametri si comporta in modo nuovo: from deve essere un matrice che contiene le coppie stringa -> stringa da sostituire nella stringa sorgente. strtr() cercherà sempre prima di incrociare il testo più lungo e *NON* tenterà di sostituire parti su cui ha già lavorato.

Esempio 2. Esempio di uso di strtr() con due parametri

<?php
$trans = array("hello" => "hi", "hi" => "hello");
echo strtr("hi all, I said hello", $trans);
?>

Questo visualizzerà:

hello all, I said hi

Nota: I parametri opzionali to e from sono stati aggiunti in PHP 4.0.0

Vedere anche ereg_replace().

substr_compare

(PHP 5)

substr_compare -- Confronto tra due stringhe a partire da una data posizione per n caratteri, sicuro con i dati binari e, opzionalmente, senza distinguere tra lettere maiuscole e minuscole

Descrizione

int substr_compare ( string main_str, string str, int offset [, int length [, bool case_insensitivity]] )

La funzione substr_compare() confronta main_str dalla posizione offset con la stringa str per length caratteri di lunghezza.

Restituisce < 0 se main_str dalla posizione offset è minore di str, > 0 se è maggiore di str, e 0 se sono uguali. Se length è uguale o maggiore della lunghezza di main_str ed è impostato il parametro length, substr_compare() visualizza un warning e restituisce FALSE.

Se case_insensitivity è TRUE, il confronto non distingue tra lettere maiuscole e minuscole.

Esempio 1. Esempio di uso di substr_compare()
<?php echo substr_compare("abcde", "bc", 1, 2); // 0 echo substr_compare("abcde", "bcg", 1, 2); // 0 echo substr_compare("abcde", "BC", 1, 2, true); // 0 echo substr_compare("abcde", "bc", 1, 3); // 1 echo substr_compare("abcde", "cd", 1, 2); // -1 echo substr_compare("abcde", "abc", 5, 1); // warning ?>

substr_count

(PHP 4, PHP 5)

substr_count -- Conta il numero di occorrenze di un segmento di stringa

Descrizione

int substr_count ( string haystack, string needle )

substr_count() restituisce il numero di volte in cui la stringa needle compare in haystack. Fare attenzione che needle distingue tra lettere maiuscole e minuscole.

Esempio 1. Esempio di uso di substr_count()
<?php echo substr_count("This is a test", "is"); // prints out 2 ?>

Vedere anche count_chars(), strpos(), substr() e strstr().

substr_replace

(PHP 4, PHP 5)

substr_replace -- Sostuisce una porzione di testo

Descrizione

string substr_replace ( string string, string replacement, int start [, int length] )

La funzione substr_replace() sostituisce una copia di string delimitata dai parametri start e (opzionalmente) length con il testo indicato in replacement. Viene restituito il testo risultante.

Se start è positivo, la sostituzione inizierà palla posizione start di string.

Se start è negativo, la sostituzione inizierà da start caratteri dalla fine di string.

Se è indicato il parametro length ed è positivo, indica il numero di caratteri del testo string che devono essere sostituiti. Se questo parametro è negativo, indica il numero di caratteri dalla fine di string a cui fermarsi nella sostituzione. Se non viene indicato, si utilizzerà il default strlen( string ); ad esempio si finirà la sostituzione alla fine di string.

Esempio 1. Esempio di uso di substr_replace()
<?php $var = 'ABCDEFGH:/MNRPQR/'; echo "Original: $var<hr />\n"; /* Questi due esempi sostituiscono tutte le occorrenze di $var con 'bob'. */ echo substr_replace($var, 'bob', 0) . "<br />\n"; echo substr_replace($var, 'bob', 0, strlen($var)) . "<br />\n"; /* Inserisce 'bob' a destra all'inizio di $var. */ echo substr_replace($var, 'bob', 0, 0) . "<br />\n"; /* Nei successivi due esempi si sostituisce 'MNRPQR' in $var con 'bob'. */ echo substr_replace($var, 'bob', 10, -1) . "<br />\n"; echo substr_replace($var, 'bob', -7, -1) . "<br />\n"; /* Cancella 'MNRPQR' da $var. */ echo substr_replace($var, '', 10, -1) . "<br />\n"; ?>

Nota: Questa funzione è binary-safe (gestisce correttamente i file binari)

Vedere anche str_replace() e substr().

substr

(PHP 3, PHP 4, PHP 5)

substr -- Restituisce parte di una stringa

Descrizione

string substr ( string string, int start [, int length] )

La funzione substr() restituisce la porzione di string indicata dai parametri start e length.

Se start non è negativo, la stringa restituita inizierà dalla posizione start di string, partendo da zero. Ad esempio, nella stringa 'abcdef', il carattere alla posizione 0 è 'a', il carattere alla posizione 2 è 'c', e così via.

Esempio 1. Esempi di base di substr()

<?php
echo substr('abcdef', 1);     // bcdef
echo substr('abcdef', 1, 3);  // bcd
echo substr('abcdef', 0, 4);  // abcd
echo substr('abcdef', 0, 8);  // abcdef
echo substr('abcdef', -1, 1); // f

// Accedere al singolo carattere
//  tramite le parentesi graffe è un'altra possibilità
$string = 'abcdef';
echo $string{0};                 // a
echo $string{3};                 // d
echo $string{strlen($string)-1}; // f
?>

Se start è negativo, la stringa restituita inizierà dal carattere start dalla fine di string.

Esempio 2. Utilizzo di valori negativi di start

<?php
$rest = substr("abcdef", -1);    // restituisce "f"
$rest = substr("abcdef", -2);    // restituisce "ef"
$rest = substr("abcdef", -3, 1); // restituisce "d"
?>

Se length è indicato ed è positivo, la stringa restituita conterrà almeno length caratteri partendo da start (in base alla lunghezza di string). Se string è minore o uguale a start, la funzione restituisce FALSE

Se length è indicato ed è negativo, allora saranno omessi length caratteri dalla fine di string (dopo avere calcolato la posizione iniziale, nel caso in cui start sia negativo). Se start indica una posizione successiva a questo troncamento, la funzione restituirà una stringa vuota.

Esempio 3. Utilizzo di valori negativi per length

<?php
$rest = substr("abcdef", 0, -1);  // returns "abcde"
$rest = substr("abcdef", 2, -1);  // returns "cde"
$rest = substr("abcdef", 4, -4);  // returns ""
$rest = substr("abcdef", -3, -1); // returns "de"
?>

Vedere anche strrchr(), substr_replace(), ereg(), trim(), mb_substr() e wordwrap().

trim

(PHP 3, PHP 4, PHP 5)

trim -- Rimuove gli spazi (ed altri caratteri) all'inizio e alla fine di un testo

Descrizione

string trim ( string str [, string charlist] )

Questa funzione restituisce il parametro str privo degli spazi iniziali e finali. Senza la specifica del secondo parametro, trim() rimuoverà questi caratteri:

" " (ASCII 32 (0x20)), spazio.
"\t" (ASCII 9 (0x09)), il carattere tab.
"\n" (ASCII 10 (0x0A)), il new line (line feed).
"\r" (ASCII 13 (0x0D)), il carriage return.
"\0" (ASCII 0 (0x00)), il byte NUL.
"\x0B" (ASCII 11 (0x0B)), il tab verticale.

Elenco dei parametri

str: La stringa che deve essere troncata.
charlist: Opzionale, Si può, inoltre, specificare quali caratteri si desidera rimuovere elencandoli in charlist. Questo parametro è un semplice elenco dei caratteri da rimuovere. Con .. si può indicare un range di caratteri.

Valori restituiti

La stringa troncata.

Log delle modifiche

Versione	Descrizione
4.1.0	E' stato aggiunto il parametro opzionale `charlist`.

Esempi

Esempio 1. Esempio di uso di trim()
<?php $text = "\t\tThese are a few words :) ... "; echo trim($text); // "These are a few words :) ..." echo trim($text, " \t."); // "These are a few words :)" // rimuove i caratteri di controllo ASCII all'inizio ed alla fine di $binary // (da 0 a 31 compresi) $clean = trim($binary, "\x00..\x1F"); ?>

Esempio 2. Trimming array values with trim()
<?php function trim_value(&$value) { $value = trim($value); } $fruit = array('apple','banana ', ' cranberry '); var_dump($fruit); array_walk($fruit, 'trim_value'); var_dump($fruit); ?>
Il precedente esempio visualizzerà:
array(3) { [0]=> string(5) "apple" [1]=> string(7) "banana " [2]=> string(11) " cranberry " } array(3) { [0]=> string(5) "apple" [1]=> string(6) "banana" [2]=> string(9) "cranberry" }

Vedere anche:

ltrim()

rtrim()

ucfirst

(PHP 3, PHP 4, PHP 5)

ucfirst -- Converte in maiuscolo il primo carattere del testo

Descrizione

string ucfirst ( string str )

Restituisce un testo in cui il primo carattere di str è maiuscolo, se si tratta di una carattere alfabetico.

Attenzione che i 'caratteri alfabetici' sono determinati dalle impostazioni locali. Ad esempio nelle impostazioni locali "C" di default, caratteri tipo ä non saranno convertiti.
Esempio 1. Esempio di uso di ucfirst()
<?php $foo = 'hello world!'; $foo = ucfirst($foo); // Hello world! $bar = 'HELLO WORLD!'; $bar = ucfirst($bar); // HELLO WORLD! $bar = ucfirst(strtolower($bar)); // Hello world! ?>

Vedere anche strtolower(), strtoupper() e ucwords().

ucwords

(PHP 3 >= 3.0.3, PHP 4, PHP 5)

ucwords -- Converte in maiuscolo il primo carattere di ogni parola di una stringa

Descrizione

string ucwords ( string str )

Restituisce un testo in cui la lettera iniziale di ogni parola è convertita in maiuscolo, se il carattere è alfabetico.

Definizione di parola: sequenza di caratteri immediatamente seguita da un carattere di delimitazione (i delimitatori sono: spazio, form-feed, newline, carriage return, tab orizzontale e tab verticale).

Esempio 1. Esempio di uso di ucwords()
<?php $foo = 'hello world!'; $foo = ucwords($foo); // Hello World! $bar = 'HELLO WORLD!'; $bar = ucwords($bar); // HELLO WORLD! $bar = ucwords(strtolower($bar)); // Hello World! ?>

Nota: Questa funzione è binary-safe (gestisce correttamente i file binari)

Vedere anche strtoupper(), strtolower() e ucfirst().

vfprintf

(PHP 5)

vfprintf -- Scrive una stringa formatta in un flusso

Descrizione

int vfprintf ( resource handle, string format, array args )

Scrive la stringa prodotta in base a format sul flusso indicato da handle. format è descritto nella documentazione di sprintf().

La funzione agisce come fprintf() ma accetta una matrice di argomenti, piuttosto che un numero variabile di argomenti.

Restituisce la lunghezza della stringa prodotta.

Vedere anche printf(), sprintf(), sscanf(), fscanf(), vsprintf() e number_format().

Esempio

Esempio 1. vfprintf(): interi completati con zero
<?php if (!($fp = fopen('date.txt', 'w'))) return; vfprintf($fp, "%04d-%02d-%02d", array($year, $month, $day)); // will write the formatted ISO date to date.txt ?>

vprintf

(PHP 4 >= 4.1.0, PHP 5)

vprintf -- Visualizza una stringa formattata

Descrizione

int vprintf ( string format, array args )

Visualizza i valori di una matrice come stringa formattata in base a format (che è descritto nella documentazione di sprintf()).

Agisce come printf() ma accetta una matrice di argomenti, piuttosto che un numero variabile di argomenti.

Restituisce la lunghezza della stringa prodotta.

Vedere anche printf(), sprintf(), e vsprintf()

vsprintf

(PHP 4 >= 4.1.0, PHP 5)

vsprintf -- Restituisce una stringa formattata

Descrizione

string vsprintf ( string format, array args )

Restituisce i valori di una matrice come testo formattato in base a format (descritto nella documentazione di sprintf()).

Agisce come sprintf() ma accetta una matrice di argomenti, piuttosto che un numero variabile di argomenti.

Vedere anche sprintf() e vprintf()

wordwrap

(PHP 4 >= 4.0.2, PHP 5)

wordwrap -- Divide una stringa ad un certo numero di caratteri utilizzando il carattere di divisione

Descrizione

string wordwrap ( string str [, int width [, string break [, bool cut]]] )

Restituisce una stringa con str suddivisa alla colonna indicata dal parametro opzionale width. La linea è interrotta utilizzando il parametro opzionale break.

wordwrap() interrompe automaticamente la stringa alla colonna 75 ed utilizza come carattere di interruzione '\n' (newline), se non sono dati width e break

Se il parametro cut è impostato a 1, la stringa è sempre interrotta alla lunghezza indicata. Pertanto se una parola supera la larghezza data, questa verrà interrotta. (Vedere il secondo esempio).

Nota: Il parametro opzionale cut è stato aggiunto in PHP 4.0.3

Esempio 1. Esempio di uso di wordwrap()

<?php
$text = "The quick brown fox jumped over the lazy dog.";
$newtext = wordwrap($text, 20, "<br />\n");

echo $newtext;
?>

Questo esempio visualizza:

The quick brown fox<br />
jumped over the lazy<br />
dog.

Esempio 2. Esempio di uso di wordwrap()

<?php
$text = "A very long woooooooooooord.";
$newtext = wordwrap($text, 8, "\n", 1);

echo "$newtext\n";
?>

Questo esempio visualizza:

A very
long
wooooooo
ooooord.

Vedere anche nl2br() e chunk_split().

CXLVI. Shockwave Flash Functions

Introduzione

PHP offers the ability to create Shockwave Flash files via Paul Haeberli's libswf module.

Nota: SWF support was added in PHP 4 RC2.
The libswf does not have support for Windows. The development of that library has been stopped, and the source is not available to port it to another systems.
For up to date SWF support take a look at the MING functions.

Requisiti

You need the libswf library to compile PHP with support for this extension. You can download libswf at ftp://ftp.sgi.com/sgi/graphics/grafica/flash/.

Installazione

Once you have libswf all you need to do is to configure --with-swf[=DIR] where DIR is a location containing the directories include and lib. The include directory has to contain the swf.h file and the lib directory has to contain the libswf.a file. If you unpack the libswf distribution the two files will be in one directory. Consequently you will have to copy the files to the proper location manually.

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

MOD_COLOR (integer)
MOD_MATRIX (integer)
TYPE_PUSHBUTTON (integer)
TYPE_MENUBUTTON (integer)
BSHitTest (float)
BSDown (float)
BSOver (float)
BSUp (float)
OverDowntoIdle (integer)
IdletoOverDown (integer)
OutDowntoIdle (integer)
OutDowntoOverDown (integer)
OverDowntoOutDown (integer)
OverUptoOverDown (integer)
OverUptoIdle (integer)
IdletoOverUp (integer)
ButtonEnter (integer)
ButtonExit (integer)
MenuEnter (integer)
MenuExit (integer)

Esempi

Once you've successfully installed PHP with Shockwave Flash support you can then go about creating Shockwave files from PHP. You would be surprised at what you can do, take the following code:
Esempio 1. SWF example
<?php swf_openfile("test.swf", 256, 256, 30, 1, 1, 1); swf_ortho2(-100, 100, -100, 100); swf_defineline(1, -70, 0, 70, 0, .2); swf_definerect(4, 60, -10, 70, 0, 0); swf_definerect(5, -60, 0, -70, 10, 0); swf_addcolor(0, 0, 0, 0); swf_definefont(10, "Mod"); swf_fontsize(5); swf_fontslant(10); swf_definetext(11, "This be Flash wit PHP!", 1); swf_pushmatrix(); swf_translate(-50, 80, 0); swf_placeobject(11, 60); swf_popmatrix(); for ($i = 0; $i < 30; $i++) { $p = $i/(30-1); swf_pushmatrix(); swf_scale(1-($p*.9), 1, 1); swf_rotate(60*$p, 'z'); swf_translate(20+20*$p, $p/1.5, 0); swf_rotate(270*$p, 'z'); swf_addcolor($p, 0, $p/1.2, -$p); swf_placeobject(1, 50); swf_placeobject(4, 50); swf_placeobject(5, 50); swf_popmatrix(); swf_showframe(); } for ($i = 0; $i < 30; $i++) { swf_removeobject(50); if (($i%4) == 0) { swf_showframe(); } } swf_startdoaction(); swf_actionstop(); swf_enddoaction(); swf_closefile(); ?>

Sommario
swf_actiongeturl -- Get a URL from a Shockwave Flash movie
swf_actiongotoframe -- Play a frame and then stop
swf_actiongotolabel -- Display a frame with the specified label
swf_actionnextframe -- Go forward one frame
swf_actionplay -- Start playing the flash movie from the current frame
swf_actionprevframe -- Go backwards one frame
swf_actionsettarget -- Set the context for actions
swf_actionstop -- Stop playing the flash movie at the current frame
swf_actiontogglequality -- Toggle between low and high quality
swf_actionwaitforframe -- Skip actions if a frame has not been loaded
swf_addbuttonrecord -- Controls location, appearance and active area of the current button
swf_addcolor -- Set the global add color to the rgba value specified
swf_closefile -- Close the current Shockwave Flash file
swf_definebitmap -- Define a bitmap
swf_definefont -- Defines a font
swf_defineline -- Define a line
swf_definepoly -- Define a polygon
swf_definerect -- Define a rectangle
swf_definetext -- Define a text string
swf_endbutton -- End the definition of the current button
swf_enddoaction -- End the current action
swf_endshape -- Completes the definition of the current shape
swf_endsymbol -- End the definition of a symbol
swf_fontsize -- Change the font size
swf_fontslant -- Set the font slant
swf_fonttracking -- Set the current font tracking
swf_getbitmapinfo -- Get information about a bitmap
swf_getfontinfo -- The height in pixels of a capital A and a lowercase x
swf_getframe -- Get the frame number of the current frame
swf_labelframe -- Label the current frame
swf_lookat -- Define a viewing transformation
swf_modifyobject -- Modify an object
swf_mulcolor -- Sets the global multiply color to the rgba value specified
swf_nextid -- Returns the next free object id
swf_oncondition -- Describe a transition used to trigger an action list
swf_openfile -- Open a new Shockwave Flash file
swf_ortho2 -- Defines 2D orthographic mapping of user coordinates onto the current viewport
swf_ortho -- Defines an orthographic mapping of user coordinates onto the current viewport
swf_perspective -- Define a perspective projection transformation
swf_placeobject -- Place an object onto the screen
swf_polarview -- Define the viewer's position with polar coordinates
swf_popmatrix -- Restore a previous transformation matrix
swf_posround -- Enables or Disables the rounding of the translation when objects are placed or moved
swf_pushmatrix -- Push the current transformation matrix back unto the stack
swf_removeobject -- Remove an object
swf_rotate -- Rotate the current transformation
swf_scale -- Scale the current transformation
swf_setfont -- Change the current font
swf_setframe -- Switch to a specified frame
swf_shapearc -- Draw a circular arc
swf_shapecurveto3 -- Draw a cubic bezier curve
swf_shapecurveto -- Draw a quadratic bezier curve between two points
swf_shapefillbitmapclip -- Set current fill mode to clipped bitmap
swf_shapefillbitmaptile -- Set current fill mode to tiled bitmap
swf_shapefilloff -- Turns off filling
swf_shapefillsolid -- Set the current fill style to the specified color
swf_shapelinesolid -- Set the current line style
swf_shapelineto -- Draw a line
swf_shapemoveto -- Move the current position
swf_showframe -- Display the current frame
swf_startbutton -- Start the definition of a button
swf_startdoaction -- Start a description of an action list for the current frame
swf_startshape -- Start a complex shape
swf_startsymbol -- Define a symbol
swf_textwidth -- Get the width of a string
swf_translate -- Translate the current transformations
swf_viewport -- Select an area for future drawing

The swf_addcolor() function sets the global add color to the rgba color specified. This color is then used (implicitly) by the swf_placeobject(), swf_modifyobject() and the swf_addbuttonrecord() functions. The color of the object will be add by the rgba values when the object is written to the screen.

Nota: The rgba values can be either positive or negative.

swf_closefile

(PHP 4, PECL)

swf_closefile -- Close the current Shockwave Flash file

Description

array swf_getbitmapinfo ( int bitmapid )

The swf_getbitmapinfo() function returns an array of information about a bitmap given by the bitmapid parameter. The returned array has the following elements:

"size" - The size in bytes of the bitmap.
"width" - The width in pixels of the bitmap.
"height" - The height in pixels of the bitmap.

swf_getfontinfo

(PHP 4, PECL)

swf_getfontinfo -- The height in pixels of a capital A and a lowercase x

Description

array swf_getfontinfo ( void )

The swf_getfontinfo() function returns an associative array with the following parameters:

Aheight - The height in pixels of a capital A.
xheight - The height in pixels of a lowercase x.

MOD_COLOR uses the current mulcolor (specified by the function swf_mulcolor()) and addcolor (specified by the function swf_addcolor()) to color the object. MOD_MATRIX uses the current matrix to position the object.

swf_mulcolor

(PHP 4, PECL)

swf_mulcolor -- Sets the global multiply color to the rgba value specified

Description

void swf_mulcolor ( float r, float g, float b, float a )

The swf_mulcolor() function sets the global multiply color to the rgba color specified. This color is then used (implicitly) by the swf_placeobject(), swf_modifyobject() and the swf_addbuttonrecord() functions. The color of the object will be multiplied by the rgba values when the object is written to the screen.

Nota: The rgba values can be either positive or negative.

swf_nextid

void swf_openfile ( string filename, float width, float height, float framerate, float r, float g, float b )

void swf_perspective ( float fovy, float aspect, float near, float far )

The swf_perspective() function defines a perspective projection transformation. The fovy parameter is field-of-view angle in the y direction. The aspect parameter should be set to the aspect ratio of the viewport that is being drawn onto. The near parameter is the near clipping plane and the far parameter is the far clipping plane.

Nota: Various distortion artifacts may appear when performing a perspective projection, this is because Flash players only have a two dimensional matrix. Some are not to pretty.

swf_placeobject

(PHP 4, PECL)

swf_placeobject -- Place an object onto the screen

Description

void swf_placeobject ( int objid, int depth )

Places the object specified by objid in the current frame at a depth of depth. The objid parameter and the depth must be between 1 and 65535.

This uses the current mulcolor (specified by swf_mulcolor()) and the current addcolor (specified by swf_addcolor()) to color the object and it uses the current matrix to position the object.

Nota: Full RGBA colors are supported.

CXLVII. Sybase Functions

Introduzione

Requisiti

Installazione

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.

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

Tabella 1. Sybase configuration options

Name	Default	Changeable	Changelog
sybase.allow_persistent	"1"	PHP_INI_ALL	Available since PHP 4.0.3.
sybase.max_persistent	"-1"	PHP_INI_ALL	Available since PHP 4.0.3.
sybase.max_links	"-1"	PHP_INI_ALL	Available since 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

Breve descrizione dei parametri di configurazione.

sybase.allow_persistent boolean: Whether to allow persistent Sybase connections.
sybase.max_persistent integer: The maximum number of persistent Sybase connections per process. -1 means no limit.
sybase.max_links integer: The maximum number of Sybase connections per process, including persistent connections. -1 means no limit.
sybase.min_error_severity integer: Minimum error severity to display.
sybase.min_message_severity integer: Minimum message severity to display.
sybase.compatability_mode boolean: Compatibility mode with old versions of PHP 3.0. If on, this will cause PHP to automatically assign types to results according to their Sybase type, instead of treating them all as strings. This compatibility mode will probably not stay around forever, so try applying whatever necessary changes to your code, and turn it off.
magic_quotes_sybase boolean: If magic_quotes_sybase is on, a single-quote is escaped with a single-quote instead of a backslash if magic_quotes_gpc or magic_quotes_runtime are enabled.
Nota: Note that when magic_quotes_sybase is ON it completely overrides magic_quotes_gpc. In this case even when magic_quotes_gpc is enabled neither double quotes, backslashes or NUL's will be escaped.

Tabella 2. Sybase-CT configuration options

Name	Default	Changeable	Changelog
sybct.allow_persistent	"1"	PHP_INI_SYSTEM	Available since PHP 4.0.4.
sybct.max_persistent	"-1"	PHP_INI_SYSTEM	Available since PHP 4.0.4.
sybct.max_links	"-1"	PHP_INI_SYSTEM	Available since PHP 4.0.4.
sybct.min_server_severity	"10"	PHP_INI_ALL	Available since PHP 4.0.4.
sybct.min_client_severity	"10"	PHP_INI_ALL	Available since PHP 4.0.4.
sybct.hostname	NULL	PHP_INI_ALL	Available since PHP 4.0.4.
sybct.deadlock_retry_count	"0"	PHP_INI_ALL	Available since PHP 4.3.0.

Breve descrizione dei parametri di configurazione.

sybct.allow_persistent boolean: Whether to allow persistent Sybase-CT connections. The default is on.
sybct.max_persistent integer: The maximum number of persistent Sybase-CT connections per process. The default is -1 meaning unlimited.
sybct.max_links integer: The maximum number of Sybase-CT connections per process, including persistent connections. The default is -1 meaning unlimited.
sybct.min_server_severity integer: 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_severity integer: 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_timeout integer: 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.timeout integer: 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.hostname string: The name of the host you claim to be connecting from, for display by sp_who. The default is none.
sybct.deadlock_retry_count int: Allows you to define how often deadlocks are to be retried. The default is -1, or "forever".

Per maggiori dettagli sulle costanti PHP_INI_* vedere Appendice G.

Tipi di risorse

Costanti predefinite

Questa estensione non definisce alcuna costante.

Sommario
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

sybase_affected_rows

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

sybase_affected_rows -- Gets number of affected rows in last query

Description

int sybase_affected_rows ( [resource 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. If the link identifier isn't specified, the last opened link is assumed.

Esempio 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()); ?>
Il precedente esempio visualizzerà:
Records deleted: 10

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().

sybase_close

(PHP 3, PHP 4, PHP 5)

sybase_close -- Closes a Sybase connection

Description

bool sybase_close ( [resource link_identifier] )

sybase_close() closes the link to a Sybase database that's associated with the specified link link_identifier. If the link identifier isn't specified, the last opened link is assumed.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

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().

sybase_connect

(PHP 3, PHP 4, PHP 5)

sybase_connect -- Opens a Sybase server connection

Description

resource sybase_connect ( [string servername [, string username [, string password [, string charset [, string appname]]]]] )

Returns a positive Sybase link identifier on success, or FALSE on failure.

sybase_connect() establishes a connection to a Sybase server. The servername argument has to be a valid servername that is defined in the 'interfaces' file.

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().

Esempio 1. sybase_connect() example
<?php $link = sybase_connect('SYBASE', '', '') or die("Could not connect !"); echo "Connected successfully"; sybase_close($link); ?>

sybase_data_seek

(PHP 3, PHP 4, PHP 5)

sybase_data_seek -- Moves internal row pointer

Description

bool sybase_data_seek ( resource result_identifier, int row_number )

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

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.

sybase_deadlock_retry_count

(PHP 4 >= 4.3.0, PHP 5)

sybase_deadlock_retry_count -- Sets the deadlock retry count

Description

void sybase_deadlock_retry_count ( int 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.

Nota: Questa funzione è disponibile soltanto usando la libreria CT e non la libreria DB.

Tabella 1. Values for retry_count

-1	Retry forever (default)
0	Do not retry
n	Retry n times

sybase_fetch_array

(PHP 3, PHP 4, PHP 5)

sybase_fetch_array -- Fetch row as array

Description

array sybase_fetch_array ( resource result )

Returns an array that corresponds to the fetched row, or FALSE if there are no more rows.

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.

Nota: 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.

Esempio 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) }

sybase_fetch_assoc

(PHP 4 >= 4.3.0, PHP 5)

sybase_fetch_assoc -- Fetch a result row as an associative array

Description

array sybase_fetch_assoc ( resource result )

Returns an array that corresponds to the fetched row, or FALSE if there are no more rows.

Nota: Questa funzione è disponibile soltanto usando la libreria CT e non la libreria DB.

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.

sybase_fetch_field

(PHP 3, PHP 4, PHP 5)

sybase_fetch_field -- Get field information from a result

Description

object sybase_fetch_field ( resource result [, int field_offset] )

Returns an object containing field information.

sybase_fetch_field() can be used in order to obtain information about fields in a certain query result. If the field offset isn't specified, the next field that wasn't yet retrieved by sybase_fetch_field() is retrieved.

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 3, PHP 4, PHP 5)

sybase_fetch_object -- Fetch a row as an object

Description

object sybase_fetch_object ( resource result [, mixed object] )

Returns an object with properties that correspond to the fetched row, or FALSE if there are no more rows.

sybase_fetch_object() is similar to sybase_fetch_assoc(), with one difference - an object is returned, instead of an array.

Use the second object to specify the type of object you want to return. If this parameter is omitted, the object will be of type stdClass.

Nota: As of PHP 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"
}
New behaviour:
object(stdclass)(3) {
  ["foo"]=>
  string(3) "foo"
  ["bar"]=>
  string(3) "bar"
}

Esempio 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()); // {...] ?>

Speed-wise, the function is identical to sybase_fetch_array(), and almost as quick as sybase_fetch_row() (the difference is insignificant).

sybase_fetch_row

(PHP 3, PHP 4, PHP 5)

sybase_fetch_row -- Get a result row as an enumerated array

Description

array sybase_fetch_row ( resource result )

Returns an array that corresponds to the fetched row, or FALSE if there are no more rows.

sybase_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 sybase_fetch_row() would return the next row in the result set, or FALSE if there are no more rows.

Tabella 1. Data types

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

sybase_field_seek

(PHP 3, PHP 4, PHP 5)

sybase_field_seek -- Sets field offset

Description

bool sybase_field_seek ( resource result, int field_offset )

void sybase_min_client_severity ( int severity )

sybase_min_client_severity() sets the minimum client severity level.

Nota: Questa funzione è disponibile soltanto usando la libreria CT e non la libreria DB.

sybase_min_error_severity

(PHP 3, PHP 4, PHP 5)

sybase_min_error_severity -- Sets minimum error severity

Description

void sybase_min_error_severity ( int severity )

sybase_min_error_severity() sets the minimum error severity level.

Nota: This function is only available using the DB library interface to Sybase, and not the CT library.

sybase_min_message_severity

(PHP 3, PHP 4, PHP 5)

sybase_min_message_severity -- Sets minimum message severity

Description

void sybase_min_message_severity ( int severity )

sybase_min_message_severity() sets the minimum message severity level.

Nota: This function is only available using the DB library interface to Sybase, and not the CT library.

sybase_min_server_severity

(PHP 3, PHP 4, PHP 5)

sybase_min_server_severity -- Sets minimum server severity

Description

void sybase_min_server_severity ( int severity )

sybase_min_server_severity() sets the minimum server severity level.

Nota: Questa funzione è disponibile soltanto usando la libreria CT e non la libreria DB.

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'.

sybase_query

(PHP 3, PHP 4, PHP 5)

sybase_query -- Sends a Sybase query

Description

mixed sybase_query ( string query [, resource link_identifier] )

Returns a positive Sybase result identifier on success, FALSE on error, or TRUE if the query was successful but didn't return any columns.

sybase_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.

sybase_result

(PHP 3, PHP 4, PHP 5)

sybase_result -- Get result data

Description

string sybase_result ( resource result, int row, mixed field )

Returns the contents of the cell at the row and offset in the specified Sybase result set.

sybase_result() returns the contents of one cell from a Sybase result set. 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.

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().

sybase_select_db

(PHP 3, PHP 4, PHP 5)

sybase_select_db -- Selects a Sybase database

Description

bool sybase_select_db ( string database_name [, resource link_identifier] )

sybase_select_db() sets the current active database on the server that's associated with the specified 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.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Every subsequent call to sybase_query() will be made on the active database.

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

Description

bool sybase_set_message_handler ( callback handler [, resource connection] )

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.

Nota: Questa funzione è disponibile soltanto usando la libreria CT e non la libreria DB.

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.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Nota: The connection parameter was added in PHP 4.3.5.

Esempio 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'); ?>

Esempio 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')); ?>

Esempio 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'); ?>

sybase_unbuffered_query

(PHP 4 >= 4.3.0, PHP 5)

sybase_unbuffered_query -- Send a Sybase query and do not block

Description

resource sybase_unbuffered_query ( string query, resource link_identifier [, bool store_result] )

Returns a positive Sybase result identifier on success, or FALSE on error.

Nota: Questa funzione è disponibile soltanto usando la libreria CT e non la libreria DB.

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.

Nota: 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.

The optional store_result can be FALSE to indicate the resultsets shouldn't be fetched into memory, thus minimizing memory usage which is particularly interesting with very large resultsets.

Esempio 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); ?>

CXLVIII. TCP Wrappers Functions

Introduzione

The TCP wrappers provides a classical unix mechanism which has been designed to check if the remote client is able to connect from the given IP address.

Installazione

Tcpwrap is currently available through PECL http://pecl.php.net/package/tcpwrap.

If PEAR is available on your *nix-like system you can use the pear installer to install the tcpwrap extension, by the following command: pear -v install tcpwrap.

You can always download the tar.gz package and install tcpwrap by hand:
Esempio 1. tcpwrap install by hand
gunzip tcpwrap-xxx.tgz tar -xvf tcpwrap-xxx.tar cd tcpwrap-xxx phpize ./configure && make && make install

Sommario
tcpwrap_check -- Performs a tcpwrap check

tcpwrap_check

(PECL)

tcpwrap_check -- Performs a tcpwrap check

Descrizione

bool tcpwrap_check ( string daemon, string address [, string user [, bool nodns]] )

This function consults the /etc/hosts.allow and /etc/hosts.deny files to check if access to service daemon should be granted or denied for a client.

Elenco dei parametri

daemon: The service name.
address: The client remote address. Can be either an IP address or a domain name.
user: An optional user name.
nodns: If address looks like domain name then DNS is used to resolve it to IP address; set nodns to TRUE to avoid this.

Valori restituiti

This function returns TRUE if access should be granted, FALSE otherwise.

Esempi

Esempio 1. Deny all connections from localhost

If your /etc/hosts.deny file contains:

php: 127.0.0.1

And your code looks like:

<?php
if (!tcpwrap_check('php', $_SERVER['REMOTE_ADDR'])) {
  die('You are not welcome here');
}
?>

Vedere anche:

For more details please consult hosts_access(3) man page.

CXLIX. Tidy Functions

Introduzione

Tidy is a binding for the Tidy HTML clean and repair utility which allows you to not only clean and otherwise manipulate HTML documents, but also traverse the document tree.

Requisiti

To use Tidy, you will need libtidy installed, available on the tidy homepage http://tidy.sourceforge.net/.

Installazione

Tidy is currently available for PHP 4.3.x and PHP 5 as a PECL extension from http://pecl.php.net/package/tidy.

Nota: Tidy 1.0 is just for PHP 4.3.x, while Tidy 2.0 is just for PHP 5.

If PEAR is available on your *nix-like system you can use the pear installer to install the tidy extension, by the following command: pear -v install tidy.

You can always download the tar.gz package and install tidy by hand:
Esempio 1. tidy install by hand in PHP 4.3.x
gunzip tidy-xxx.tgz tar -xvf tidy-xxx.tar cd tidy-xxx phpize ./configure && make && make install

Windows users can download the extension dll php_tidy.dll from http://snaps.php.net/win32/PECL_STABLE/.

In PHP 5 you need only to compile using the --with-tidy option.

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

Tabella 1. Tidy Configuration Options

Name	Default	Changeable	Changelog
tidy.default_config	""	PHP_INI_SYSTEM	Available since PHP 5.0.0.
tidy.clean_output	"0"	PHP_INI_PERDIR	Available since PHP 5.0.0.

Per maggiori dettagli sulle costanti PHP_INI_* vedere Appendice G.

Breve descrizione dei parametri di configurazione.

tidy.default_config string

Default path for tidy config file.

tidy.clean_output boolean

Turns on/off the output repairing by Tidy.

Avvertimento

Do not turn on tidy.clean_output if you are generating non-html content such as dynamic images.

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Classi predefinite

tidyNode

Metodi

tidyNode->hasChildren - Returns TRUE if the current node has childrens
tidyNode->hasSiblings - Returns TRUE if the current node has siblings
tidyNode->isAsp - Returns TRUE if the current node is ASP code
tidyNode->isComment - Returns TRUE if the current node is a comment
tidyNode->isHtml - Returns TRUE if the current node is HTML
tidyNode->isJste - Returns TRUE if the current node is JSTE
tidyNode->isPhp - Returns TRUE if the current node is PHP
tidyNode->isText - Returns TRUE if the current node is Text (no markup)

Proprietà

value - the value of the node (e.g. the html text)
name - the name of the tag (e.g. html, a, etc..)
type - the type of the node (one of the constants above, e.g. TIDY_NODETYPE_PHP)
line* - the line where the node starts
column* - the column where the node starts
proprietary* - TRUE if the node refers to a proprietary tag
id - the ID of the tag (one of the constants above, e.g. TIDY_TAG_FRAME)
attribute - an array with the attributes of the current node, or NULL if there aren't any
child - an array with the child tidyNodes, or NULL if there aren't any

Nota: The properties marked with * are just available since PHP 5.1.0.

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

Each TIDY_TAG_XXX represents a HTML tag. For example, TIDY_TAG_A represents a <a href="XX">link</a> tag. Each TIDY_ATTR_XXX represents a HTML atribute. For example TIDY_ATTR_HREF would represent the href atribute in the previous example.

The following constants are defined:

Tabella 2. tidy tag constants

constant
TIDY_TAG_UNKNOWN
TIDY_TAG_A
TIDY_TAG_ABBR
TIDY_TAG_ACRONYM
TIDY_TAG_ALIGN
TIDY_TAG_APPLET
TIDY_TAG_AREA
TIDY_TAG_B
TIDY_TAG_BASE
TIDY_TAG_BASEFONT
TIDY_TAG_BDO
TIDY_TAG_BGSOUND
TIDY_TAG_BIG
TIDY_TAG_BLINK
TIDY_TAG_BLOCKQUOTE
TIDY_TAG_BODY
TIDY_TAG_BR
TIDY_TAG_BUTTON
TIDY_TAG_CAPTION
TIDY_TAG_CENTER
TIDY_TAG_CITE
TIDY_TAG_CODE
TIDY_TAG_COL
TIDY_TAG_COLGROUP
TIDY_TAG_COMMENT
TIDY_TAG_DD
TIDY_TAG_DEL
TIDY_TAG_DFN
TIDY_TAG_DIR
TIDY_TAG_DIV
TIDY_TAG_DL
TIDY_TAG_DT
TIDY_TAG_EM
TIDY_TAG_EMBED
TIDY_TAG_FIELDSET
TIDY_TAG_FONT
TIDY_TAG_FORM
TIDY_TAG_FRAME
TIDY_TAG_FRAMESET
TIDY_TAG_H1
TIDY_TAG_H2
TIDY_TAG_H3
TIDY_TAG_H4
TIDY_TAG_H5
TIDY_TAG_H6
TIDY_TAG_HEAD
TIDY_TAG_HR
TIDY_TAG_HTML
TIDY_TAG_I
TIDY_TAG_IFRAME
TIDY_TAG_ILAYER
TIDY_TAG_IMG
TIDY_TAG_INPUT
TIDY_TAG_INS
TIDY_TAG_ISINDEX
TIDY_TAG_KBD
TIDY_TAG_KEYGEN
TIDY_TAG_LABEL
TIDY_TAG_LAYER
TIDY_TAG_LEGEND
TIDY_TAG_LI
TIDY_TAG_LINK
TIDY_TAG_LISTING
TIDY_TAG_MAP
TIDY_TAG_MARQUEE
TIDY_TAG_MENU
TIDY_TAG_META
TIDY_TAG_MULTICOL
TIDY_TAG_NOBR
TIDY_TAG_NOEMBED
TIDY_TAG_NOFRAMES
TIDY_TAG_NOLAYER
TIDY_TAG_NOSAFE
TIDY_TAG_NOSCRIPT
TIDY_TAG_OBJECT
TIDY_TAG_OL
TIDY_TAG_OPTGROUP
TIDY_TAG_OPTION
TIDY_TAG_P
TIDY_TAG_PARAM
TIDY_TAG_PLAINTEXT
TIDY_TAG_PRE
TIDY_TAG_Q
TIDY_TAG_RP
TIDY_TAG_RT
TIDY_TAG_RTC
TIDY_TAG_RUBY
TIDY_TAG_S
TIDY_TAG_SAMP
TIDY_TAG_SCRIPT
TIDY_TAG_SELECT
TIDY_TAG_SERVER
TIDY_TAG_SERVLET
TIDY_TAG_SMALL
TIDY_TAG_SPACER
TIDY_TAG_SPAN
TIDY_TAG_STRIKE
TIDY_TAG_STRONG
TIDY_TAG_STYLE
TIDY_TAG_SUB
TIDY_TAG_TABLE
TIDY_TAG_TBODY
TIDY_TAG_TD
TIDY_TAG_TEXTAREA
TIDY_TAG_TFOOT
TIDY_TAG_TH
TIDY_TAG_THEAD
TIDY_TAG_TITLE
TIDY_TAG_TR
TIDY_TAG_TR
TIDY_TAG_TT
TIDY_TAG_U
TIDY_TAG_UL
TIDY_TAG_VAR
TIDY_TAG_WBR
TIDY_TAG_XMP

Tabella 3. tidy attribute constants

constant
TIDY_ATTR_UNKNOWN
TIDY_ATTR_ABBR
TIDY_ATTR_ACCEPT
TIDY_ATTR_ACCEPT_CHARSET
TIDY_ATTR_ACCESSKEY
TIDY_ATTR_ACTION
TIDY_ATTR_ADD_DATE
TIDY_ATTR_ALIGN
TIDY_ATTR_ALINK
TIDY_ATTR_ALT
TIDY_ATTR_ARCHIVE
TIDY_ATTR_AXIS
TIDY_ATTR_BACKGROUND
TIDY_ATTR_BGCOLOR
TIDY_ATTR_BGPROPERTIES
TIDY_ATTR_BORDER
TIDY_ATTR_BORDERCOLOR
TIDY_ATTR_BOTTOMMARGIN
TIDY_ATTR_CELLPADDING
TIDY_ATTR_CELLSPACING
TIDY_ATTR_CHAR
TIDY_ATTR_CHAROFF
TIDY_ATTR_CHARSET
TIDY_ATTR_CHECKED
TIDY_ATTR_CITE
TIDY_ATTR_CLASS
TIDY_ATTR_CLASSID
TIDY_ATTR_CLEAR
TIDY_ATTR_CODE
TIDY_ATTR_CODEBASE
TIDY_ATTR_CODETYPE
TIDY_ATTR_COLOR
TIDY_ATTR_COLS
TIDY_ATTR_COLSPAN
TIDY_ATTR_COMPACT
TIDY_ATTR_CONTENT
TIDY_ATTR_COORDS
TIDY_ATTR_DATA
TIDY_ATTR_DATAFLD
TIDY_ATTR_DATAPAGESIZE
TIDY_ATTR_DATASRC
TIDY_ATTR_DATETIME
TIDY_ATTR_DECLARE
TIDY_ATTR_DEFER
TIDY_ATTR_DIR
TIDY_ATTR_DISABLED
TIDY_ATTR_ENCODING
TIDY_ATTR_ENCTYPE
TIDY_ATTR_FACE
TIDY_ATTR_FOR
TIDY_ATTR_FRAME
TIDY_ATTR_FRAMEBORDER
TIDY_ATTR_FRAMESPACING
TIDY_ATTR_GRIDX
TIDY_ATTR_GRIDY
TIDY_ATTR_HEADERS
TIDY_ATTR_HEIGHT
TIDY_ATTR_HREF
TIDY_ATTR_HREFLANG
TIDY_ATTR_HSPACE
TIDY_ATTR_HTTP_EQUIV
TIDY_ATTR_ID
TIDY_ATTR_ISMAP
TIDY_ATTR_LABEL
TIDY_ATTR_LANG
TIDY_ATTR_LANGUAGE
TIDY_ATTR_LAST_MODIFIED
TIDY_ATTR_LAST_VISIT
TIDY_ATTR_LEFTMARGIN
TIDY_ATTR_LINK
TIDY_ATTR_LONGDESC
TIDY_ATTR_LOWSRC
TIDY_ATTR_MARGINHEIGHT
TIDY_ATTR_MARGINWIDTH
TIDY_ATTR_MAXLENGTH
TIDY_ATTR_MEDIA
TIDY_ATTR_METHOD
TIDY_ATTR_MULTIPLE
TIDY_ATTR_NAME
TIDY_ATTR_NOHREF
TIDY_ATTR_NORESIZE
TIDY_ATTR_NOSHADE
TIDY_ATTR_NOWRAP
TIDY_ATTR_OBJECT
TIDY_ATTR_OnAFTERUPDATE
TIDY_ATTR_OnBEFOREUNLOAD
TIDY_ATTR_OnBEFOREUPDATE
TIDY_ATTR_OnBLUR
TIDY_ATTR_OnCHANGE
TIDY_ATTR_OnCLICK
TIDY_ATTR_OnDATAAVAILABLE
TIDY_ATTR_OnDATASETCHANGED
TIDY_ATTR_OnDATASETCOMPLETE
TIDY_ATTR_OnDBLCLICK
TIDY_ATTR_OnERRORUPDATE
TIDY_ATTR_OnFOCUS
TIDY_ATTR_OnKEYDOWN
TIDY_ATTR_OnKEYPRESS
TIDY_ATTR_OnKEYUP
TIDY_ATTR_OnLOAD
TIDY_ATTR_OnMOUSEDOWN
TIDY_ATTR_OnMOUSEMOVE
TIDY_ATTR_OnMOUSEOUT
TIDY_ATTR_OnMOUSEOVER
TIDY_ATTR_OnMOUSEUP
TIDY_ATTR_OnRESET
TIDY_ATTR_OnROWENTER
TIDY_ATTR_OnROWEXIT
TIDY_ATTR_OnSELECT
TIDY_ATTR_OnSUBMIT
TIDY_ATTR_OnUNLOAD
TIDY_ATTR_PROFILE
TIDY_ATTR_PROMPT
TIDY_ATTR_RBSPAN
TIDY_ATTR_READONLY
TIDY_ATTR_REL
TIDY_ATTR_REV
TIDY_ATTR_RIGHTMARGIN
TIDY_ATTR_ROWS
TIDY_ATTR_ROWSPAN
TIDY_ATTR_RULES
TIDY_ATTR_SCHEME
TIDY_ATTR_SCOPE
TIDY_ATTR_SCROLLING
TIDY_ATTR_SELECTED
TIDY_ATTR_SHAPE
TIDY_ATTR_SHOWGRID
TIDY_ATTR_SHOWGRIDX
TIDY_ATTR_SHOWGRIDY
TIDY_ATTR_SIZE
TIDY_ATTR_SPAN
TIDY_ATTR_SRC
TIDY_ATTR_STANDBY
TIDY_ATTR_START
TIDY_ATTR_STYLE
TIDY_ATTR_SUMMARY
TIDY_ATTR_TABINDEX
TIDY_ATTR_TARGET
TIDY_ATTR_TEXT
TIDY_ATTR_TITLE
TIDY_ATTR_TOPMARGIN
TIDY_ATTR_TYPE
TIDY_ATTR_USEMAP
TIDY_ATTR_VALIGN
TIDY_ATTR_VALUE
TIDY_ATTR_VALUETYPE
TIDY_ATTR_VERSION
TIDY_ATTR_VLINK
TIDY_ATTR_VSPACE
TIDY_ATTR_WIDTH
TIDY_ATTR_WRAP
TIDY_ATTR_XML_LANG
TIDY_ATTR_XML_SPACE
TIDY_ATTR_XMLNS

Tabella 4. tidy nodetype constants

constant	description
TIDY_NODETYPE_ROOT	root node
TIDY_NODETYPE_DOCTYPE	doctype
TIDY_NODETYPE_COMMENT	HTML comment
TIDY_NODETYPE_PROCINS	Processing Instruction
TIDY_NODETYPE_TEXT	Text
TIDY_NODETYPE_START	start tag
TIDY_NODETYPE_END	end tag
TIDY_NODETYPE_STARTEND	empty tag
TIDY_NODETYPE_CDATA	CDATA
TIDY_NODETYPE_SECTION	XML section
TIDY_NODETYPE_ASP	ASP code
TIDY_NODETYPE_JSTE	JSTE code
TIDY_NODETYPE_PHP	PHP code
TIDY_NODETYPE_XMLDECL	XML declaration

Esempi

This simple example shows basic Tidy usage.
Esempio 2. Basic Tidy usage
<?php ob_start(); ?> <html>a html document</html> <? $html = ob_get_clean(); // Specify configuration $config = array( 'indent' => true, 'output-xhtml' => true, 'wrap' => 200); // Tidy $tidy = new tidy; $tidy->parseString($html, $config, 'utf8'); $tidy->cleanRepair(); // Output echo $tidy; ?>

Sommario
ob_tidyhandler -- ob_start callback function to repair the buffer
tidy_access_count -- Returns the Number of Tidy accessibility warnings encountered for specified document
tidy_clean_repair -- Execute configured cleanup and repair operations on parsed markup
tidy_config_count -- Returns the Number of Tidy configuration errors encountered for specified document
tidy::__construct -- Constructs a new tidy object
tidy_diagnose -- Run configured diagnostics on parsed and repaired markup
tidy_error_count -- Returns the Number of Tidy errors encountered for specified document
tidy_get_body -- Returns a tidyNode Object starting from the <body> tag of the tidy parse tree
tidy_get_config -- Get current Tidy configuration
tidy_get_error_buffer -- Return warnings and errors which occurred parsing the specified document
tidy_get_head -- Returns a tidyNode Object starting from the <head> tag of the tidy parse tree
tidy_get_html_ver -- Get the Detected HTML version for the specified document
tidy_get_html -- Returns a tidyNode Object starting from the <html> tag of the tidy parse tree
tidy_get_opt_doc -- Returns the documentation for the given option name
tidy_get_output -- Return a string representing the parsed tidy markup
tidy_get_release -- Get release date (version) for Tidy library
tidy_get_root -- Returns a tidyNode object representing the root of the tidy parse tree
tidy_get_status -- Get status of specified document
tidy_getopt -- Returns the value of the specified configuration option for the tidy document
tidy_is_xhtml -- Indicates if the document is a XHTML document
tidy_is_xml -- Indicates if the document is a generic (non HTML/XHTML) XML document
tidy_load_config -- Load an ASCII Tidy configuration file with the specified encoding
tidy_node->get_attr -- Return the attribute with the provided attribute id
tidy_node->get_nodes -- Return an array of nodes under this node with the specified id
tidy_node->next -- Returns the next sibling to this node
tidy_node->prev -- Returns the previous sibling to this node
tidy_parse_file -- Parse markup in file or URI
tidy_parse_string -- Parse a document stored in a string
tidy_repair_file -- Repair a file and return it as a string
tidy_repair_string -- Repair a string using an optionally provided configuration file
tidy_reset_config -- Restore Tidy configuration to default values
tidy_save_config -- Save current settings to named file
tidy_set_encoding -- Set the input/output character encoding for parsing markup
tidy_setopt -- Updates the configuration settings for the specified tidy document
tidy_warning_count -- Returns the Number of Tidy warnings encountered for specified document
tidyNode->hasChildren -- Returns true if this node has children
tidyNode->hasSiblings -- Returns true if this node has siblings
tidyNode->isAsp -- Returns true if this node is ASP
tidyNode->isComment -- Returns true if this node represents a comment
tidyNode->isHtml -- Returns true if this node is part of a HTML document
tidyNode->isJste -- Returns true if this node is JSTE
tidyNode->isPhp -- Returns true if this node is PHP
tidyNode->isText -- Returns true if this node represents text (no markup)

ob_tidyhandler

(PHP 5)

ob_tidyhandler -- ob_start callback function to repair the buffer

Description

string ob_tidyhandler ( string input [, int mode] )

ob_tidyhandler() is intended to be used as a callback function for ob_start() to repair the buffer.

Esempio 1. ob_tidyhandler() example
<?php ob_start('ob_tidyhandler'); echo '<p>test</i>'; ?>
Il precedente esempio visualizzerà:
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN"> <html> <head> <title></title> </head> <body> <p>test</p> </body> </html>

tidy_access_count

(PHP 5)

tidy_access_count -- Returns the Number of Tidy accessibility warnings encountered for specified document

Description

int tidy_access_count ( tidy object )

tidy_access_count() returns the number of accessibility warnings found for the specified document.

Nota: Due to the design of the TidyLib, you must call tidy_diagnose() before tidy_access_count() or it will return always 0. You must also need to enable the accessibility-check option.

Esempio 1. tidy_access_count() example
<?php $html ='<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN"> <html><head><title>Title</title></head> <body> <p><img src="img.png"></p> </body></html>'; // select the accessibility check level: 1, 2 or 3 $config = array('accessibility-check' => 3); $tidy = new tidy(); $tidy->parseString($html, $config); $tidy->CleanRepair(); /* Never forget to call this! */ $tidy->diagnose(); echo tidy_access_count($tidy); //5 ?>

tidy_clean_repair

(PHP 5)

tidy_clean_repair -- Execute configured cleanup and repair operations on parsed markup

Description

Procedural style:

bool tidy_clean_repair ( tidy object )

Object oriented style:

bool tidy->cleanRepair ( void )

This function cleans and repairs the given tidy object.

Esempio 1. tidy_clean_repair() example
<?php $html = '<p>test</I>'; $tidy = tidy_parse_string($html); tidy_clean_repair($tidy); echo $tidy; ?>
Il precedente esempio visualizzerà:
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN"> <html> <head> <title></title> </head> <body> <p>test</p> </body> </html>

tidy_config_count

(PHP 5)

tidy_config_count -- Returns the Number of Tidy configuration errors encountered for specified document

Description

int tidy_config_count ( tidy object )

tidy_config_count() returns the number of errors encountered in the configuration of the specified tidy object.

Esempio 1. tidy_config_count() example
<?php $html = '<p>test</I>'; $config = array('doctype' => 'bogus'); $tidy = tidy_parse_string($html, $config); /* This outputs 1, because 'bogus' isn't a valid doctype */ echo tidy_config_count($tidy); ?>

tidy::__construct

(no version information, might be only in CVS)

tidy::__construct -- Constructs a new tidy object

Description

tidy tidy::__construct ( [string filename [, mixed config [, string encoding [, bool use_include_path]]]] )

tidy::__construct() constructs a new tidy object.

If the filename parameter is given, this function will also read that file and initialize the object with the file, acting like tidy_parse_file().

Il parametro config può essere passato sia come matrice sia come stringa. Se lo si passa come stringa, questo indica il nome del file di configurazione; nel primo caso viene interpretato come impostazione di opzioni. Guardare http://tidy.sourceforge.net/docs/quickref.html per maggiori dettagli su ogni singola opzione.

Il parametro encoding imposta la codifica dei caratteri per le operazioni di input ed output. I possibili valori sono: ascii, latin1, raw, utf8, iso2022, mac, win1252, utf16le, utf16be, utf16, big5 and shiftjis.

Esempio 1. tidy::__construct() example
<?php $html = <<< HTML <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <head><title>title</title></head> <body> <p>paragraph <bt /> text</p> </body></html> HTML; $tidy = new tidy; $tidy->parseString($html); $tidy->CleanRepair(); if ($tidy->errorBuffer) { echo "The following errors were detected:\n"; echo $tidy->errorBuffer; } ?>
Il precedente esempio visualizzerà:
The following errors were detected: line 8 column 14 - Error: <bt> is not recognized! line 8 column 14 - Warning: discarding unexpected <bt>

tidy_diagnose

(PHP 5)

tidy_diagnose -- Run configured diagnostics on parsed and repaired markup

Description

Procedural style:

bool tidy_diagnose ( tidy object )

Object oriented style:

bool tidy->diagnose ( void )

tidy_diagnose() runs diagnostic tests on the given tidy object, adding some more information about the document in the error buffer.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempio 1. tidy_diagnose() example
<?php $html = <<< HTML <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <p>paragraph</p> HTML; $tidy = tidy_parse_string($html); $tidy->CleanRepair(); // note the difference between the two outputs echo tidy_get_error_buffer($tidy) . "\n"; $tidy->diagnose(); echo tidy_get_error_buffer($tidy); ?>
Il precedente esempio visualizzerà:
line 5 column 1 - Warning: <p> isn't allowed in <head> elements line 5 column 1 - Warning: inserting missing 'title' element line 5 column 1 - Warning: <p> isn't allowed in <head> elements line 5 column 1 - Warning: inserting missing 'title' element Info: Doctype given is "-//W3C//DTD XHTML 1.0 Strict//EN" Info: Document content looks like XHTML 1.0 Strict 2 warnings, 0 errors were found!

tidy_error_count

(PHP 5)

tidy_error_count -- Returns the Number of Tidy errors encountered for specified document

Description

Nota: You need at least libtidy from 25 April, 2005 for this function be available.

Elenco dei parametri

object: A tidy object
optname: The option name

Valori restituiti

Returns a string if the option exists and has documentation available, or FALSE otherwise.

Esempi

Esempio 1. Print all options along with their documentation and default value
<?php $tidy = new tidy; $config = $tidy->getConfig(); ksort($config); foreach ($config as $opt => $val) { if (!$doc = $tidy->getOptDoc($opt)) $doc = 'no documentation available!'; $val = ($tidy->getOpt($opt) === true) ? 'true' : $val; $val = ($tidy->getOpt($opt) === false) ? 'false' : $val; echo "<p><b>$opt</b> (default: '$val')<br />". "$doc</p><hr />\n"; } ?>

Vedere anche:

tidy_get_config()

tidy_getopt()

tidy_get_output

(PHP 5)

tidy_get_output -- Return a string representing the parsed tidy markup

Description

string tidy_get_output ( tidy object )

tidy_get_output() returns a string with the repaired html.

Esempio 1. tidy_get_output() example
<?php $html = '<p>paragraph</i>'; $tidy = tidy_parse_string($html); $tidy->CleanRepair(); echo tidy_get_output($tidy); ?>
Il precedente esempio visualizzerà:
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN"> <html> <head> <title></title> </head> <body> <p>paragraph</p> </body> </html>

tidy_get_release

(PHP 5)

tidy_get_release -- Get release date (version) for Tidy library

Description

Procedural style:

string tidy_get_release ( void )

Object oriented style:

string tidy->getRelease ( void )

This function returns a string with the release date of the Tidy library.

tidy_get_root

(PHP 5)

tidy_get_root -- Returns a tidyNode object representing the root of the tidy parse tree

Description

Procedural style:

tidyNode tidy_get_root ( tidy object )

Object oriented style:

tidyNode tidy->root ( void )

Returns a tidyNode object representing the root of the tidy parse tree.

Esempio 1. dump nodes
<?php $html = <<< HTML <html><body> <p>paragraph</p> <br/> </body></html> HTML; $tidy = tidy_parse_string($html); dump_nodes($tidy->root(), 1); function dump_nodes($node, $indent) { if($node->hasChildren()) { foreach($node->child as $child) { echo str_repeat('.', $indent*2) . ($child->name ? $child->name : '"'.$child->value.'"'). "\n"; dump_nodes($child, $indent+1); } } } ?>
Il precedente esempio visualizzerà:
..html ....head ......title ....body ......p ........"paragraph" ......br

Nota: Questa funzione è disponibile solo con Zend Engine 2, ciò implica PHP >= 5.0.0.

This function is not yet implemented in the Tidylib itself, so it always return FALSE.

tidy_is_xml

(PHP 5)

tidy_is_xml -- Indicates if the document is a generic (non HTML/XHTML) XML document

Description

Procedural style:

bool tidy_is_xml ( tidy object )

Object oriented style:

bool tidy->isXml ( void )

Procedural style:

tidy tidy_parse_file ( string filename [, mixed config [, string encoding [, bool use_include_path]]] )

Object oriented style:

bool tidy->parseFile ( string filename [, mixed config [, string encoding [, bool use_include_path]]] )

This function parses the given file.

Esempio 1. tidy_parse_file() example
<?php $tidy = tidy_parse_file('file.html'); $tidy->cleanRepair(); if(!empty($tidy->errorBuffer)) { echo "The following errors or warnings occured:\n"; echo $tidy->errorBuffer; } ?>

Nota: I parametri opzionali config e encoding sono stati aggiunti in Tidy 2.0.

tidy_parse_string

(PHP 5)

tidy_parse_string -- Parse a document stored in a string

Description

Procedural style:

tidy tidy_parse_string ( string input [, mixed config [, string encoding]] )

Object oriented style:

bool tidy->parseString ( string input [, mixed config [, string encoding]] )

tidy_parse_string() parses a document stored in a string.

Esempio 1. tidy_parse_string() example
<?php ob_start(); ?> <html> <head> <title>test</title> </head> <body> <p>error<br>another line</i> </body> </html> <?php $buffer = ob_get_clean(); $config = array('indent' => TRUE, 'output-xhtml' => TRUE, 'wrap' => 200); $tidy = tidy_parse_string($buffer, $config, 'UTF8'); $tidy->cleanRepair(); echo $tidy; ?>
Il precedente esempio visualizzerà:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <title> test </title> </head> <body> <p> error<br /> another line </p> </body> </html>

Nota: I parametri opzionali config e encoding sono stati aggiunti in Tidy 2.0.

tidy_repair_file

(PHP 5)

tidy_repair_file -- Repair a file and return it as a string

Description

string tidy_repair_file ( string filename [, mixed config [, string encoding [, bool use_include_path]]] )

This function repairs the given file and returns it as a string.

Esempio 1. tidy_repair_file() example
<?php $file = 'file.html'; $repaired = tidy_repair_file($file); rename($file, $file . '.bak'); file_put_contents($file, $repaired); ?>

Nota: I parametri opzionali config e encoding sono stati aggiunti in Tidy 2.0.

tidy_repair_string

(PHP 5)

tidy_repair_string -- Repair a string using an optionally provided configuration file

Description

string tidy_repair_string ( string data [, mixed config [, string encoding]] )

This function repairs the given string.

Esempio 1. tidy_repair_string() example
<?php ob_start(); ?> <html> <head> <title>test</title> </head> <body> <p>error</i> </body> </html> <?php $buffer = ob_get_clean(); $tidy = tidy_repair_string($buffer); echo $tidy; ?>
Il precedente esempio visualizzerà:
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN"> <html> <head> <title>test</title> </head> <body> <p>error</p> </body> </html>

Nota: I parametri opzionali config e encoding sono stati aggiunti in Tidy 2.0.

tidy_reset_config

(no version information, might be only in CVS)

tidy_reset_config -- Restore Tidy configuration to default values

Description

bool tidy_reset_config ( void )

This function restores the Tidy configuration to the default values.

Nota: Questa funzione ` disponibile soltanto in Tidy 1.0. Sarà obsoleta in Tidy 2.0, e quindi sar` rimossa.

tidy_save_config

(no version information, might be only in CVS)

tidy_save_config -- Save current settings to named file

Description

bool tidy_save_config ( string filename )

tidy_save_config() saves current settings to the specified file. Only non-default values are written.

Nota: Questa funzione ` disponibile soltanto in Tidy 1.0. Sarà obsoleta in Tidy 2.0, e quindi sar` rimossa.

tidy_set_encoding

(no version information, might be only in CVS)

tidy_set_encoding -- Set the input/output character encoding for parsing markup

Description

bool tidy_set_encoding ( string encoding )

Sets the encoding for input/output documents. Restituisce TRUE in caso di successo, FALSE in caso di fallimento. Possible values for encoding are ascii, latin0, latin1, raw, utf8, iso2022, mac, win1252, ibm858, utf16, utf16le, utf16be, big5 and shiftjis

Nota: Questa funzione ` disponibile soltanto in Tidy 1.0. Sarà obsoleta in Tidy 2.0, e quindi sar` rimossa.

tidy_setopt

(no version information, might be only in CVS)

tidy_setopt -- Updates the configuration settings for the specified tidy document

Description

bool tidy_setopt ( string option, mixed value )

tidy_setopt() updates the specified option with a new value.

Esempio 1. tidy_setopt() example
<?php $html = '<p>test</i>'; $tidy = tidy_parse_string($html); tidy_setopt('indent', FALSE); ?>

Nota: Questa funzione ` disponibile soltanto in Tidy 1.0. Sarà obsoleta in Tidy 2.0, e quindi sar` rimossa.

tidy_warning_count

(PHP 5)

tidy_warning_count -- Returns the Number of Tidy warnings encountered for specified document

Description

This functions returns TRUE if the current node is ASP, or FALSE otherwise.

Nota: This function was named tidy_node->is_asp() in PHP 4/Tidy 1.

tidyNode->isComment

(no version information, might be only in CVS)

tidyNode->isComment -- Returns true if this node represents a comment

Description

bool tidyNode->isComment ( void )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Nota: This function was named tidy_node->is_comment() in PHP 4/Tidy 1.

tidyNode->isHtml

(no version information, might be only in CVS)

tidyNode->isHtml -- Returns true if this node is part of a HTML document

Description

bool tidyNode->isHtml ( void )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Nota: This function was named tidy_node->is_html() in PHP 4/Tidy 1.

tidyNode->isJste

(no version information, might be only in CVS)

tidyNode->isJste -- Returns true if this node is JSTE

Description

bool tidyNode->isJste ( void )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Nota: This function was named tidy_node->is_jste() in PHP 4/Tidy 1.

tidyNode->isPhp

(no version information, might be only in CVS)

tidyNode->isPhp -- Returns true if this node is PHP

Description

bool tidyNode->isPhp ( void )

Returns TRUE if the current node is PHP code, FALSE otherwise.

Esempio 1. get the PHP code from a mixed HTML/PHP document
<?php $html = <<< HTML <html><head> <?php echo '<title>title</title>'; ?> </head> <body> <?php echo 'hello world!'; ?> </body></html> HTML; $tidy = tidy_parse_string($html); $num = 0; get_php($tidy->html()); function get_php($node) { // check if the current node is PHP code if($node->isPhp()) { echo "\n\n# PHP node #" . ++$GLOBALS['num'] . "\n"; echo $node->value; } // check if the current node has childrens if($node->hasChildren()) { foreach($node->child as $child) { get_php($child); } } } ?>
Il precedente esempio visualizzerà:
# PHP node #1 <?php echo '<title>title</title>'; ?> # PHP node #2 <?php echo 'hello world!'; ?>

Nota: This function was named tidy_node->is_php() in PHP 4/Tidy 1.

tidyNode->isText

(no version information, might be only in CVS)

tidyNode->isText -- Returns true if this node represents text (no markup)

Description

bool tidyNode->isText ( void )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Nota: This function was named tidy_node->is_text() in PHP 4/Tidy 1.

CL. Tokenizer Functions

Introduzione

The tokenizer functions provide an interface to the PHP tokenizer embedded in the Zend Engine. Using these functions you may write your own PHP source analyzing or modification tools without having to deal with the language specification at the lexical level.

Requisiti

Non sono necessarie librerie esterne per utilizzare questo modulo.

Installazione

Beginning with PHP 4.3.0 these functions are enabled by default. For older versions you have to configure and compile PHP with --enable-tokenizer. You can disable tokenizer support with --disable-tokenizer.

La versione per Windows di PHP ha già compilato il supporto per questo modulo. Non occorre caricare alcun modulo addizionale per potere utilizzare queste funzioni.

Nota: Builtin support for tokenizer is available with PHP 4.3.0.

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

T_INCLUDE (integer)
T_INCLUDE_ONCE (integer)
T_EVAL (integer)
T_REQUIRE (integer)
T_REQUIRE_ONCE (integer)
T_LOGICAL_OR (integer)
T_LOGICAL_XOR (integer)
T_LOGICAL_AND (integer)
T_PRINT (integer)
T_PLUS_EQUAL (integer)
T_MINUS_EQUAL (integer)
T_MUL_EQUAL (integer)
T_DIV_EQUAL (integer)
T_CONCAT_EQUAL (integer)
T_MOD_EQUAL (integer)
T_AND_EQUAL (integer)
T_OR_EQUAL (integer)
T_XOR_EQUAL (integer)
T_SL_EQUAL (integer)
T_SR_EQUAL (integer)
T_BOOLEAN_OR (integer)
T_BOOLEAN_AND (integer)
T_IS_EQUAL (integer)
T_IS_NOT_EQUAL (integer)
T_IS_IDENTICAL (integer)
T_IS_NOT_IDENTICAL (integer)
T_IS_SMALLER_OR_EQUAL (integer)
T_IS_GREATER_OR_EQUAL (integer)
T_SL (integer)
T_SR (integer)
T_INC (integer)
T_DEC (integer)
T_INT_CAST (integer)
T_DOUBLE_CAST (integer)
T_STRING_CAST (integer)
T_ARRAY_CAST (integer)
T_OBJECT_CAST (integer)
T_BOOL_CAST (integer)
T_UNSET_CAST (integer)
T_NEW (integer)
T_EXIT (integer)
T_IF (integer)
T_ELSEIF (integer)
T_ELSE (integer)
T_ENDIF (integer)
T_LNUMBER (integer)
T_DNUMBER (integer)
T_STRING (integer)
T_STRING_VARNAME (integer)
T_VARIABLE (integer)
T_NUM_STRING (integer)
T_INLINE_HTML (integer)
T_CHARACTER (integer)
T_BAD_CHARACTER (integer)
T_ENCAPSED_AND_WHITESPACE (integer)
T_CONSTANT_ENCAPSED_STRING (integer)
T_ECHO (integer)
T_DO (integer)
T_WHILE (integer)
T_ENDWHILE (integer)
T_FOR (integer)
T_ENDFOR (integer)
T_FOREACH (integer)
T_ENDFOREACH (integer)
T_DECLARE (integer)
T_ENDDECLARE (integer)
T_AS (integer)
T_SWITCH (integer)
T_ENDSWITCH (integer)
T_CASE (integer)
T_DEFAULT (integer)
T_BREAK (integer)
T_CONTINUE (integer)
T_OLD_FUNCTION (integer): T_OLD_FUNCTION is not defined in PHP 5.
T_FUNCTION (integer)
T_CONST (integer)
T_RETURN (integer)
T_USE (integer)
T_GLOBAL (integer)
T_STATIC (integer)
T_VAR (integer)
T_UNSET (integer)
T_ISSET (integer)
T_EMPTY (integer)
T_CLASS (integer)
T_EXTENDS (integer)
T_OBJECT_OPERATOR (integer)
T_DOUBLE_ARROW (integer)
T_LIST (integer)
T_ARRAY (integer)
T_LINE (integer)
T_FILE (integer)
T_COMMENT (integer)
T_ML_COMMENT (integer): T_ML_COMMENT is not defined in PHP 5. All comments in PHP 5 are of token T_COMMENT.
T_DOC_COMMENT (integer): T_DOC_COMMENT was introduced in PHP 5.
T_OPEN_TAG (integer)
T_OPEN_TAG_WITH_ECHO (integer)
T_CLOSE_TAG (integer)
T_WHITESPACE (integer)
T_START_HEREDOC (integer)
T_END_HEREDOC (integer)
T_DOLLAR_OPEN_CURLY_BRACES (integer)
T_CURLY_OPEN (integer)
T_PAAMAYIM_NEKUDOTAYIM (integer)
T_DOUBLE_COLON (integer)
T_INTERFACE (integer): PHP 5 only.
T_IMPLEMENTS (integer): PHP 5 only.
T_CLASS_C (integer): PHP 5 only.
T_FUNC_C (integer): PHP 5 only.
T_METHOD_C (integer): PHP 5 only.
T_ABSTRACT (integer): PHP 5 only.
T_CATCH (integer): PHP 5 only.
T_FINAL (integer): PHP 5 only.
T_INSTANCEOF (integer): PHP 5 only.
T_PRIVATE (integer): PHP 5 only.
T_PROTECTED (integer): PHP 5 only.
T_PUBLIC (integer): PHP 5 only.
T_THROW (integer): PHP 5 only.
T_TRY (integer): PHP 5 only.
T_CLONE (integer): PHP 5 only.

Esempi

Here is a simple example PHP scripts using the tokenizer that will read in a PHP file, strip all comments from the source and print the pure code only.

Esempio 1. Strip comments with the tokenizer

<?php
/*
 * T_ML_COMMENT does not exist in PHP 5.
 * The following three lines define it in order to
 * preserve backwards compatibility.
 *
 * The next two lines define the PHP 5 only T_DOC_COMMENT,
 * which we will mask as T_ML_COMMENT for PHP 4.
 */
if (!defined('T_ML_COMMENT')) {
    define('T_ML_COMMENT', T_COMMENT);
} else {
    define('T_DOC_COMMENT', T_ML_COMMENT);
}

$source = file_get_contents('example.php');
$tokens = token_get_all($source);

foreach ($tokens as $token) {
    if (is_string($token)) {
        // simple 1-character token
        echo $token;
    } else {
        // token array
        list($id, $text) = $token;
 
        switch ($id) { 
            case T_COMMENT: 
            case T_ML_COMMENT: // we've defined this
            case T_DOC_COMMENT: // and this
                // no action on comments
                break;

            default:
                // anything else -> output "as is"
                echo $text;
                break;
        }
    }
}
?>

Sommario
token_get_all -- Split given source into PHP tokens
token_name -- Get the symbolic name of a given PHP token

token_get_all

(PHP 4 >= 4.2.0, PHP 5)

token_get_all -- Split given source into PHP tokens

Descrizione

array token_get_all ( string source )

token_get_all() parses the given source string into PHP language tokens using the Zend engine's lexical scanner.

For a list of parser tokens, see Appendice Q, or use token_name() to translate a token value into its string representation.

Elenco dei parametri

source: The PHP source to parse.

Valori restituiti

An array of token identifiers. Each individual token identifier is either a single character (i.e.: ;, ., >, !, etc...), or a two element array containing the token index in element 0, and the string content of the original token in element 1.

Esempi

Esempio 1. token_get_all() examples
<?php $tokens = token_get_all('<?php echo; ?>'); /* => array( array(T_OPEN_TAG, '<?php'), array(T_ECHO, 'echo'), ';', array(T_CLOSE_TAG, '?>') ); */ /* Note in the following example that the string is parsed as T_INLINE_HTML rather than the otherwise expected T_COMMENT (T_ML_COMMENT in PHP <5). This is because no open/close tags were used in the "code" provided. This would be equivalent to putting a comment outside of <?php ?> tags in a normal file. */ $tokens = token_get_all('/* comment */'); // => array(array(T_INLINE_HTML, '/* comment */')); ?>

token_name

(PHP 4 >= 4.2.0, PHP 5)

token_name -- Get the symbolic name of a given PHP token

Descrizione

string token_name ( int token )

token_name() gets the symbolic name for a PHP token value.

Elenco dei parametri

token: The token value.

Valori restituiti

The symbolic name of the given token. The returned name returned matches the name of the matching token constant.

Esempi

Esempio 1. token_name() example
<?php // 260 is the token value for the T_REQUIRE token echo token_name(260); // -> "T_REQUIRE" // a token constant maps to its own name echo token_name(T_FUNCTION); // -> "T_FUNCTION" ?>

Vedere anche:

List of Parser Tokens

CLI. Unicode Functions

Introduzione

Unicode Support.

Avvertimento

This extension is still in development and it isn't available to public yet.

Requisiti

ICU 3.4 or later is required.

Installazione

First you should download and install ICU:
Esempio 1. install ICU on Unix
./configure --disable-threads --enable-extras --enable-icuio --enable-layout make && make install

Then checkout latest PHP and configure it --with-icu-dir=<dir> option, where <dir> was the dir to where you installed ICU. You don't need to explicitly use this option if you install ICU to a standard location.

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

Tabella 1. Unicode Configuration Options

Name	Default	Changeable	Changelog
unicode.fallback_encoding	NULL	PHP_INI_ALL	Available since PHP 6.0.0.
unicode.from_error_mode	2	PHP_INI_ALL	Available since PHP 6.0.0.
unicode.from_error_subst_char	"3f"	PHP_INI_ALL	Available since PHP 6.0.0.
unicode.http_input_encoding	NULL	PHP_INI_ALL	Available since PHP 6.0.0.
unicode.output_encoding	NULL	PHP_INI_ALL	Available since PHP 6.0.0.
unicode.runtime_encoding	NULL	PHP_INI_ALL	Available since PHP 6.0.0.
unicode.script_encoding	NULL	PHP_INI_ALL	Available since PHP 6.0.0.
unicode.semantics	off	PHP_INI_PERDIR	Available since PHP 6.0.0.

Per maggiori dettagli sulle costanti PHP_INI_* vedere Appendice G.

Breve descrizione dei parametri di configurazione.

unicode.output_encoding string: Default encoding for output.

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

Tabella 2.

constant	value	description
U_INVALID_STOP	0	stop at first invalid character
U_INVALID_SKIP	1	skip invalid characters
U_INVALID_SUBSTITUTE	2	replace invalid characters
U_INVALID_ESCAPE	3	escape invalid characters

Sommario
i18n_loc_get_default -- Get the default Locale
i18n_loc_set_default -- Set the default Locale
unicode_encode -- Takes a unicode string and converts it to a string in the specified encoding

i18n_loc_get_default

(no version information, might be only in CVS)

i18n_loc_get_default -- Get the default Locale

Descrizione

string i18n_loc_get_default ( void )

This function returns the default Locale, which is used by PHP to localize certain features. Please note that this isn't influenced by setlocale() or the system settings.

Valori restituiti

Returns a string with the current Locale.

Esempi

Esempio 1. A i18n_loc_get_default() example
<?php // get the default Locale echo i18n_loc_get_default(); //set a new Locale... i18n_loc_set_default('pt_PT'); // ... and print it echo i18n_loc_get_default(); ?>
Il precedente esempio visualizzerà:
en_US_POSIX pt_PT

Vedere anche:

i18n_loc_set_default()

i18n_loc_set_default

(no version information, might be only in CVS)

i18n_loc_set_default -- Set the default Locale

Descrizione

bool i18n_loc_set_default ( string name )

Sets the default Locale for PHP programs. Please note that this has nothing to do with setlocale() nor with the system locale.

Elenco dei parametri

name: The new Locale name. A comprehensive list of the supported locales is available at http://www-950.ibm.com/software/globalization/icu/demo/locales/en/?d_=en.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 1. A i18n_loc_set_default() example
This example demonstrates a possible usage of i18n_loc_set_default() to localize the sort() functions.
<?php // the list of the strings to sort $array = array( 'caramelo', 'cacto', 'caçada' ); // set our locale (Portuguese, in this case) i18n_loc_set_default('pt_PT'); // sort using the locale we previously set sort($array, SORT_LOCALE_STRING); print_r($array); ?>
Il precedente esempio visualizzerà:
Array ( [0] => caçada [1] => cacto [2] => caramelo )
If we didn't use the locale, PHP would sort the string using the ASCII characters value, thus returning (wrongly):
Array ( [0] => cacto [1] => caramelo [2] => caçada )

Vedere anche:

i18n_loc_get_default()

unicode_encode

(PHP 5 CVS only)

unicode_encode -- Takes a unicode string and converts it to a string in the specified encoding

Descrizione

string unicode_encode ( unicode input, string encoding )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Elenco dei parametri

input: Its description
encoding: Its description

Valori restituiti

What the function returns, first on success, then on failure.

Esempi

Esempio 1. A unicode_encode() example
Any text that describes the purpose of t
<?php if ($anexample === true) { echo 'Use the PEAR Coding Standards'; } ?>
Il precedente esempio visualizzerà:
Use the PEAR Coding Standards

Vedere anche:

unicode_decode()

CLII. URL Functions

Introduzione

Dealing with URL strings: encoding, decoding and parsing.

Requisiti

Non sono necessarie librerie esterne per utilizzare questo modulo.

Installazione

Non è necessaria nessuna installazione per usare queste funzioni, esse fanno parte del core di PHP.

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

Questa estensione non definisce alcuna costante.

Sommario
base64_decode -- Decodes data encoded with MIME base64
base64_encode -- Encodes data with MIME base64
get_headers -- Fetches all the headers sent by the server in response to a HTTP request
get_meta_tags -- Extracts all meta tag content attributes from a file and returns an array
http_build_query -- Generate URL-encoded query string
parse_url -- Parse a URL and return its components
rawurldecode -- Decode URL-encoded strings
rawurlencode -- URL-encode according to RFC 1738
urldecode -- Decodes URL-encoded string
urlencode -- URL-encodes string

base64_decode

(PHP 3, PHP 4, PHP 5)

base64_decode -- Decodes data encoded with MIME base64

Description

string base64_decode ( string encoded_data )

base64_decode() decodes encoded_data and returns the original data or FALSE on failure. The returned data may be binary.

Esempio 1. base64_decode() example
<?php $str = 'VGhpcyBpcyBhbiBlbmNvZGVkIHN0cmluZw=='; echo base64_decode($str); ?>
This example will produce:
This is an encoded string

See also base64_encode() and RFC 2045 section 6.8.

base64_encode

(PHP 3, PHP 4, PHP 5)

base64_encode -- Encodes data with MIME base64

Description

string base64_encode ( string data )

base64_encode() returns data encoded with base64. This encoding is designed to make binary data survive transport through transport layers that are not 8-bit clean, such as mail bodies.

Base64-encoded data takes about 33% more space than the original data.

Esempio 1. base64_encode() example
<?php $str = 'This is an encoded string'; echo base64_encode($str); ?>
This example will produce:
VGhpcyBpcyBhbiBlbmNvZGVkIHN0cmluZw==

See also base64_decode(), chunk_split(), convert_uuencode() and RFC 2045 section 6.8.

get_headers

(PHP 5)

get_headers -- Fetches all the headers sent by the server in response to a HTTP request

Description

array get_headers ( string url [, int format] )

get_headers() returns an array with the headers sent by the server in response to a HTTP request. Returns FALSE on failure and an error of level E_WARNING will be issued.

If the optional format parameter is set to 1, get_headers() parses the response and sets the array's keys.

Esempio 1. get_headers() example
<?php $url = 'http://www.example.com'; print_r(get_headers($url)); print_r(get_headers($url, 1)); ?>
Il precedente esempio visualizzerà qualcosa simile a:
Array ( [0] => HTTP/1.1 200 OK [1] => Date: Sat, 29 May 2004 12:28:13 GMT [2] => Server: Apache/1.3.27 (Unix) (Red-Hat/Linux) [3] => Last-Modified: Wed, 08 Jan 2003 23:11:55 GMT [4] => ETag: "3f80f-1b6-3e1cb03b" [5] => Accept-Ranges: bytes [6] => Content-Length: 438 [7] => Connection: close [8] => Content-Type: text/html ) Array ( [0] => HTTP/1.1 200 OK [Date] => Sat, 29 May 2004 12:28:14 GMT [Server] => Apache/1.3.27 (Unix) (Red-Hat/Linux) [Last-Modified] => Wed, 08 Jan 2003 23:11:55 GMT [ETag] => "3f80f-1b6-3e1cb03b" [Accept-Ranges] => bytes [Content-Length] => 438 [Connection] => close [Content-Type] => text/html )

get_meta_tags

(PHP 3 >= 3.0.4, PHP 4, PHP 5)

get_meta_tags -- Extracts all meta tag content attributes from a file and returns an array

Description

array get_meta_tags ( string filename [, bool use_include_path] )

Opens filename and parses it line by line for <meta> tags in the file. This can be a local file or an URL. The parsing stops at </head>.

Setting use_include_path to TRUE will result in PHP trying to open the file along the standard include path as per the include_path directive. This is used for local files, not URLs.

Esempio 1. What get_meta_tags() parses
<meta name="author" content="name"> <meta name="keywords" content="php documentation"> <meta name="DESCRIPTION" content="a php manual"> <meta name="geo.position" content="49.33;-86.59"> </head> 
(pay attention to line endings - PHP uses a native function to parse the input, so a Mac file won't work on Unix).

The value of the name property becomes the key, the value of the content property becomes the value of the returned array, so you can easily use standard array functions to traverse it or access single values. Special characters in the value of the name property are substituted with '_', the rest is converted to lower case. If two meta tags have the same name, only the last one is returned.

Esempio 2. What get_meta_tags() returns
<?php // Assuming the above tags are at www.example.com $tags = get_meta_tags('http://www.example.com/'); // Notice how the keys are all lowercase now, and // how . was replaced by _ in the key. echo $tags['author']; // name echo $tags['keywords']; // php documentation echo $tags['description']; // a php manual echo $tags['geo_position']; // 49.33;-86.59 ?>

Nota: As of PHP 4.0.5, get_meta_tags() supports unquoted HTML attributes.

See also htmlentities() and urlencode().

http_build_query

(PHP 5)

http_build_query -- Generate URL-encoded query string

Description

string http_build_query ( array formdata [, string numeric_prefix] )

Generates a URL-encoded query string from the associative (or indexed) array provided. formdata may be an array or object containing properties. A formdata array may be a simple one-dimensional structure, or an array of arrays (who in turn may contain other arrays). If numeric indices are used in the base array and a numeric_prefix is provided, it will be prepended to the numeric index for elements in the base array only. This is to allow for legal variable names when the data is decoded by PHP or another CGI application later on.

Nota: arg_separator.output is used to separate arguments.

Esempio 1. Simple usage of http_build_query()

<?php
$data = array('foo'=>'bar',
              'baz'=>'boom',
              'cow'=>'milk',
              'php'=>'hypertext processor');
              
echo http_build_query($data); // foo=bar&baz=boom&cow=milk&php=hypertext+processor
?>

Esempio 2. http_build_query() with numerically index elements.

<?php
$data = array('foo', 'bar', 'baz', 'boom', 'cow' => 'milk', 'php' =>'hypertext processor');
              
echo http_build_query($data);
/* Outputs:
      0=foo&1=bar&2=baz&3=boom&cow=milk&php=hypertext+processor
 */
 
echo http_build_query($data, 'myvar_');
/* Outputs:
      myvar_0=foo&myvar_1=bar&myvar_2=baz&myvar_3=boom&cow=milk&php=hypertext+processor
 */
?>

Esempio 3. http_build_query() with complex arrays

<?php
$data = array('user'=>array('name'=>'Bob Smith',
                            'age'=>47,
                            'sex'=>'M',
                            'dob'=>'5/12/1956'),
              'pastimes'=>array('golf', 'opera', 'poker', 'rap'),
              'children'=>array('bobby'=>array('age'=>12,
                                               'sex'=>'M'),
                                'sally'=>array('age'=>8,
                                               'sex'=>'F')),
              'CEO');
                                               
echo http_build_query($data, 'flags_');
?>

this will output : (word wrapped for readability)

user[name]=Bob+Smith&user[age]=47&user[sex]=M&user[dob]=5%1F12%1F1956&
pastimes[0]=golf&pastimes[1]=opera&pastimes[2]=poker&pastimes[3]=rap&
children[bobby][age]=12&children[bobby][sex]=M&children[sally][age]=8&
children[sally][sex]=F&flags_0=CEO

Nota: Only the numerically indexed element in the base array "CEO" received a prefix. The other numeric indices, found under pastimes, do not require a string prefix to be legal variable names.

Esempio 4. Using http_build_query() with an object

<?php
class myClass {
  var $foo;
  var $baz;
  
  function myClass() 
  {
    $this->foo = 'bar';
    $this->baz = 'boom';
  }
}

$data = new myClass();

echo http_build_query($data); // foo=bar&baz=boom

?>

parse_url

(PHP 3, PHP 4, PHP 5)

parse_url -- Parse a URL and return its components

Descrizione

array parse_url ( string url )

This function parses a URL and returns an associative array containing any of the various components of the URL that are present.

This function is not meant to validate the given URL, it only breaks it up into the above listed parts. Partial URLs are also accepted, parse_url() tries its best to parse them correctly.

Elenco dei parametri

url: The URL to parse

Valori restituiti

On seriously malformed URLs, parse_url() may return FALSE and emit a E_WARNING. Otherwise an associative array is returned, whose components may be (at least one):

scheme - e.g. http
host
port
user
pass
path
query - after the question mark ?
fragment - after the hashmark #

Esempi

Esempio 1. A parse_url() example
<?php $url = 'http://username:password@hostname/path?arg=value#anchor'; print_r(parse_url($url)); ?>
Il precedente esempio visualizzerà:
Array ( [scheme] => http [host] => hostname [user] => username [pass] => password [path] => /path [query] => arg=value [fragment] => anchor )

Note

Nota: This function doesn't work with relative URLs.

Vedere anche:

pathinfo()

parse_str()

dirname()

basename()

rawurldecode

(PHP 3, PHP 4, PHP 5)

rawurldecode -- Decode URL-encoded strings

Description

string rawurldecode ( string str )

Returns a string in which the sequences with percent (%) signs followed by two hex digits have been replaced with literal characters.

Esempio 1. rawurldecode() example
<?php echo rawurldecode('foo%20bar%40baz'); // foo bar@baz ?>

Nota: rawurldecode() does not decode plus symbols ('+') into spaces. urldecode() does.

Description

string urlencode ( string str )

Returns a string in which all non-alphanumeric characters except -_. have been replaced with a percent (%) sign followed by two hex digits and spaces encoded as plus (+) signs. It is encoded the same way that the posted data from a WWW form is encoded, that is the same way as in application/x-www-form-urlencoded media type. This differs from the RFC1738 encoding (see rawurlencode()) in that for historical reasons, spaces are encoded as plus (+) signs. This function is convenient when encoding a string to be used in a query part of a URL, as a convenient way to pass variables to the next page:
Esempio 1. urlencode() example
<?php echo '<a href="mycgi?foo=', urlencode($userinput), '">'; ?>

Note: Be careful about variables that may match HTML entities. Things like &amp, &copy and &pound are parsed by the browser and the actual entity is used instead of the desired variable name. This is an obvious hassle that the W3C has been telling people about for years. The reference is here: http://www.w3.org/TR/html4/appendix/notes.html#h-B.2.2. PHP supports changing the argument separator to the W3C-suggested semi-colon through the arg_separator .ini directive. Unfortunately most user agents do not send form data in this semi-colon separated format. A more portable way around this is to use & instead of & as the separator. You don't need to change PHP's arg_separator for this. Leave it as &, but simply encode your URLs using htmlentities() or htmlspecialchars().

Esempio 2. urlencode() and htmlentities() example
<?php $query_string = 'foo=' . urlencode($foo) . '&bar=' . urlencode($bar); echo '<a href="mycgi?' . htmlentities($query_string) . '">'; ?>

CLIII. Funzioni per la gestione delle variabili

Introduzione

Per maggiori informazioni sul comportamento delle variabili vedere la sezione Variabili nel capitolo Riferimento al Linguaggio del manuale.

Requisiti

Non sono necessarie librerie esterne per utilizzare questo modulo.

Installazione

Non è necessaria nessuna installazione per usare queste funzioni, esse fanno parte del core di PHP.

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

Tabella 1. Configurazioni per il modulo Variabili

Nome	Default	Modificabile	Variazioni
unserialize_callback_func	""	PHP_INI_ALL	Disponibile dal PHP 4.2.0.

Per maggiori dettagli sulle costanti PHP_INI_* vedere Appendice G.

Breve descrizione dei parametri di configurazione.

unserialize_callback_func string

La funzione di callback di de-serializzazione unserialize() viene richiamata (con il parametro "nome classe" non definito) se la funzione trova una classe indefinita da da istanziare. Verrà prodotto un warning se la funzione specificata non è definita oppure se la funzione non include/implementa la classe mancante. Pertanto valorizzare questo parametro se si desidera implementare tale funzione di callback.

Vedere anche unserialize().

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

Questa estensione non definisce alcuna costante.

Sommario
debug_zval_dump -- Dumps a string representation of an internal zend value to output
doubleval -- Alias di floatval()
empty -- Determina se una variabile è valorizzata
floatval -- Restituisce il valore di una variabile di tipo float
get_defined_vars -- Restituisce un'array contenente tutte le variabili definite
get_resource_type -- Restituisce il tipo di risorsa
gettype -- Resituisce il tipo di una variabile
import_request_variables -- Imposta la visibiltà a globale per le variabili GET/POST/Cookie
intval -- Estrae il valore intero da una variabile
is_array -- Verifica se una variabile è un array
is_bool -- Verifica se una variabile è di tipo boolean
is_callable -- Verifica se il contenuto dell'argomento può essere eseguito come funzione
is_double -- Alias di is_float()
is_float -- Verifica se una variabile è di tipo float (decimale a virgola mobile)
is_int -- Verifica se una variabile è di tipo integer
is_integer -- Alias di is_int()
is_long -- Alias di is_int()
is_null -- Verifica se la variabile è di tipo NULL
is_numeric -- Verifica se una variabile è un numero o una stringa numerica
is_object -- Verifica se una variabile è di tipo object
is_real -- Alias di is_float()
is_resource -- Verifica se una variabile è una risorsa
is_scalar -- Verifica se la variabile è di tipo scalare
is_string -- Verifica se una variabile sia una stringa
isset -- Verifica se una variabile è definita
print_r -- Stampa informazioni relative al contenuto di una variabile in formato leggibile
serialize -- Genera una versione archiviabile del valore
settype -- Definisce il tipo di una variabile
strval -- Restituisce il valore di una variabile interpretato come stringa
unserialize -- Crea un valore PHP a partire da una rappresentazione archiviata
unset -- Cancella una data variabile
var_dump -- Stampa delle informazioni relative ad una variabile
var_export -- Visualizza o restituisce una variabile in formato stringa

debug_zval_dump

(PHP 4 >= 4.2.0, PHP 5)

debug_zval_dump -- Dumps a string representation of an internal zend value to output

Descrizione

void debug_zval_dump ( mixed variable )

Dumps a string representation of an internal zend value to output.

Elenco dei parametri

variable: The variable being evaluated.

Valori restituiti

No value is returned.

Esempi

Esempio 1. debug_zval_dump() example
<?php $var1 = 'Hello World'; $var2 = ''; $var2 =& $var1; debug_zval_dump(&$var1); ?>
Il precedente esempio visualizzerà:
string(11) "Hello World" refcount(3)

Beware the refcount: The refcount value returned by this function is non-obvious in certain circumstances. For example, a developer might expect the above example to indicate a refcount of 2. The third reference is created when actually calling debug_zval_dump().
This behavior is further compounded when a variable is not passed to debug_zval_dump() by reference. To illustrate, consider a slightly modified version of the above example:
Esempio 2.
<?php
$var1 = 'Hello World';
$var2 = '';

$var2 =& $var1;

debug_zval_dump($var1); // not passed by reference, this time
?>
Il precedente esempio visualizzerà:
string(11) "Hello World" refcount(1)
Why refcount(1)? Because a copy of $var1 is being made, when the function is called.
This function becomes even more confusing when a variable with a refcount of 1 is passed (by copy/value):
Esempio 3.
<?php
$var1 = 'Hello World';

debug_zval_dump($var1);
?>
Il precedente esempio visualizzerà:
string(11) "Hello World" refcount(2)
A refcount of 2, here, is extremely non-obvious. Especially considering the above examples. So what's happening?
When a variable has a single reference (as did $var1 before it was used as an argument to debug_zval_dump()), PHP's engine optimizes the manner in which it is passed to a function. Internally, PHP treats $var1 like a reference (in that the refcount is increased for the scope of this function), with the caveat that if the passed reference happens to be written to, a copy is made, but only at the moment of writing. This is known as "copy on write."
So, if debug_zval_dump() happened to write to its sole parameter (and it doesn't), then a copy would be made. Until then, the parameter remains a reference, causing the refcount to be incremented to 2 for the scope of the function call.

Vedere anche:

var_dump()

debug_backtrace()

References Explained

doubleval

(PHP 3, PHP 4, PHP 5)

doubleval -- Alias di floatval()

Descrizione

This function is an alias of: floatval().

Log delle modifiche

Versione	Descrizione
4.2.0	doubleval() è diventato un alias di floatval(). Prima esisteva solo doubleval().

empty

(PHP 3, PHP 4, PHP 5)

empty -- Determina se una variabile è valorizzata

Descrizione

bool empty ( mixed var )

Determina se una variabile è da considerare vuota.

Elenco dei parametri

var

Varibaile da controllare

Nota: empty() agisce solo su variabili, qualsiasi altra cosa genera un errore di parsing. In altre parole, il seguente comando non funziona: empty(trim($name)).

empty() è l'opposto di (boolean) var, tranne che non viene dato alcun warning quando la variabile non è valorizzata.

Valori restituiti

Restituisce FALSE se var non è vuota ed ha un valore diverso da zero.

I seguenti valori sono considerati vuoti:

"" (stringa vuota)

0 (0 come intero)

"0" (0 come stringa)

NULL

FALSE

array() (matrice vuota)

var $var; (una variabile dichiarata, ma senza valore in una classe)

Log delle modifiche

Versione	Descrizione
PHP 5	Dal PHP 5, oggetti privi di proprietà non sono più considerati vuoti.
PHP 4	Dal PHP 4, la stringa "0" è considerata vuota.

Esempi

Esempio 1. Semplici confronti empty() / isset().
<?php $var = 0; // Valutata come true perchè $var è vuota if (empty($var)) { echo '$var is either 0, empty, or not set at all'; } // Valutata come vera perchè $var è impostata if (isset($var)) { echo '$var is set even though it is empty'; } ?>

Note

Nota: Poichè questo è un costrutto del linguaggio e non una funzione, non può essere chiamato con le variabili funzione

Vedere anche:

isset()

unset()

array_key_exists()

count()

strlen()

la tabella di comparazione dei tipi

floatval

(PHP 4 >= 4.2.0, PHP 5)

floatval -- Restituisce il valore di una variabile di tipo float

Descrizione

float floatval ( mixed var )

La funzione restituisce il valore di tipo float di var.

Elenco dei parametri

var: Può anche essere di tipo scalare. La funzione floatval() non può essere usata con variabili di tipo array oppure object.

Valori restituiti

Il valore in virgola mobile della variabile.

Esempi

Esempio 1. Esempio di uso di floatval()
<?php $var = '122.34343The'; $float_value_of_var = floatval($var); echo $float_value_of_var; // 122.34343 ?>

Vedere anche:

intval()

strval()

settype()

Type juggling

get_defined_vars

(PHP 4 >= 4.0.4, PHP 5)

get_defined_vars -- Restituisce un'array contenente tutte le variabili definite

Descrizione

array get_defined_vars ( void )

Questa funzione restituisce un'array multidimensionale contenente la lista di tutte le variabili definite, siano esse d'ambiente, variabili del server o definite dall'utente, visibili da dove get_defined_vars() viene eseguito.

Valori restituiti

Un'array multidimensionale contenente la lista di tutte le variabili definite.

Esempi

Esempio 1. Esempio di uso di get_defined_vars()
<?php $b = array(1, 1, 2, 3, 5, 8); $arr = get_defined_vars(); // visualizza $b print_r($arr["b"]); /* visualizza il percorso dell'interprete PHP (se usato come CGI) * ad esempio /usr/local/bin/php */ echo $arr["_"]; // visualizza i parametri della linea di comando (se presenti) print_r($arr["argv"]); // visualizza tutte le variabili del server print_r($arr["_SERVER"]); // visualizza tutte le chiavi disponibili nell'array delle variabili print_r(array_keys(get_defined_vars())); ?>

Log delle modifiche

Versione	Descrizione
5.0.0	La variabile `$GLOBALS` viene compresa nella matrice restituita.

Vedere anche:

isset()

get_defined_functions()

get_defined_constants()

get_resource_type

(PHP 4 >= 4.0.2, PHP 5)

get_resource_type -- Restituisce il tipo di risorsa

Descrizione

string get_resource_type ( resource handle )

Questa funzione restituisce il tipo della risorsa data.

Elenco dei parametri

handle: Risorsa da valutare.

Valori restituiti

Se il parametro handle è una risorsa, questa funzione restituirà una stringa indicante il tipo di risorsa. Se il tipo non è identificato dalla funzione, il valore restituito sarà Unknown.

La funzione restituisce FALSE e genera un errore se handle non è di tipo resource.

Esempi

Esempio 1. Esempio di uso di get_resource_type()
<?php // visualizza: mysql link $c = mysql_connect(); echo get_resource_type($c) . "\n"; // visualizza: file $fp = fopen("foo", "w"); echo get_resource_type($fp) . "\n"; // visualizza: domxml document $doc = new_xmldoc("1.0"); echo get_resource_type($doc->doc) . "\n"; ?>

gettype

(PHP 3, PHP 4, PHP 5)

gettype -- Resituisce il tipo di una variabile

Descrizione

string gettype ( mixed var )

Restituisce il tipo della variabile PHP var.

Avvertimento

Non utilizzare gettype() per testare certi tipi di variabili poichè la stringa restistuita potrebbe variare nelle versioni future. Inoltre questa funzione è lenta dato che richiede confronti tra stringhe

Piuttosto utilizzare le funzioni is_*.

La stringa restituita può assumere i seguenti valori:

"boolean" (dalla versione 4 di PHP)
"integer"
"double" (per ragioni storiche viene restituito "double" in caso di variabile di tipo float, e non semplicemente "float")
"string"
"array"
"object"
"resource" (dalla versione 4 di PHP)
"NULL" (dalla versione 4 di PHP)
"user function" (soltanto in PHP 3, deprecated)
"unknown type"

Nella versione 4 di PHP si dovrebbe applicare alle funzioni function_exists() o method_exists() al posto del precedente gettype().

Vedere anche settype(), is_array(), is_bool(), is_float(), is_int(), is_null(), is_numeric(), is_object(), is_resource(), is_scalar() e is_string().

import_request_variables

(PHP 4 >= 4.1.0, PHP 5)

import_request_variables -- Imposta la visibiltà a globale per le variabili GET/POST/Cookie

Descrizione

bool import_request_variables ( string tipo [, string prefisso] )

Imposta la visibilità delle variabili GET/POST/Cookie a globale. Ciò risulta utile nei casi in cui si è disabilitato register_globals, ma si vuole avere per qualche variabile una visibilità globale.

Tramite il parametro tipo, si può specificare quale variabile rendere visibile. I valori ammessi sono i caratteri 'G', 'P' e 'C' rispettivamente per GET, POST e Cookie. Questi caratteri non distinguono tra maiuscole e minuscole pertanto si può usare qualsiasi combinazione di 'g', 'p' e 'c'. POST include le informazioni dei file caricati. Occorre prestare attenzione all'ordine delle lettere, ad esempio usando "gp", le variabili POST sovrascrivono le variabili GET con il medesimo nome. Qualsiasi altra lettera al di fuori di GPC sarà scartata.

Il parametro prefisso viene utilizzato come prefisso nel nome della variabile, ovvero viene anteposto ai nomi di tutte le variabili portate a visibilità globale. Quindi, se si ha una variabile GET chiamata "userid", e si è passato il prefisso "pref_", si otterrà una variabile globale chiamata $pref_userid.

Se si è interessati a rendere visibili altre variabili, come ad esempio SERVER, si consideri l'utilizzo della funzione extract().

Nota: Sebbene il parametro prefisso sia opzionale, si ottiene un errore di livello E_NOTICE se non si specifica il prefisso, o si indica una stringa vuota. Ciò può comportare dei rischi di sicurezza. Gli errori di livello "notice" non sono visualizzati con il parametro error reporting impostato al valore standard.

<?php
// Questo esempio rende visibili le variabili GET e POST 
// con il prefisso "rvar_" 
import_request_variables("gP", "rvar_");

echo $rvar_foo;
?>

Vedere anche $_REQUEST, register_globals, Variabili predefinite e extract().

intval

(PHP 3, PHP 4, PHP 5)

intval -- Estrae il valore intero da una variabile

Descrizione

int intval ( mixed var [, int base] )

Estrae il valore intero di var, utilizzando la base definita a parametro per la conversione. (La base vale 10 di default).

Elenco dei parametri

var: Valore scalare da convertire in intero
base: Base per la conversione (il default è 10)

Valori restituiti

Il valore intero di var se riesce, oppure 0 in caso di errore. Le matrici e gli oggetti vuoti restituiscono 0, la matrici e gli oggetti pieni restituiscono 1.

Il valore massimo dipende dal sistema. Nei sistemi a 32 bit si ha come valore per il caso di intero con segno il range da -2147483648 a 2147483647. Così, ad esempio, su tali sistemi, la riga intval('1000000000000') restituirà 2147483647. Il massimo valore per un intero con segno sui sistemi a 64 bit è 9223372036854775807.

Le stringhe probabilmente restituiranno 0, sebbene il valore restituito dipenda dal primo carattere a sinistra della stringa. Si utilizzano le comuni di integer casting .

Esempi

Esempio 1. Esempi di uso di intval()
I seguenti esempi sono basati su un sistema a 32 bit.
<?php echo intval(42); // 42 echo intval(4.2); // 4 echo intval('42'); // 42 echo intval('+42'); // 42 echo intval('-42'); // -42 echo intval(042); // 34 echo intval('042'); // 42 echo intval(1e10); // 1410065408 echo intval('1e10'); // 1 echo intval(0x1A); // 26 echo intval(42000000); // 42000000 echo intval(420000000000000000000); // 0 echo intval('420000000000000000000'); // 2147483647 echo intval(42, 8); // 42 echo intval('42', 8); // 34 ?>

Note

Nota: Il parametro base non ha influenza a meno che il parametro var non sia una stringa.

Vedere anche:

floatval()

strval()

settype()

BCMath Arbitrary Precision Mathematics Functions

Type juggling

is_array

(PHP 3, PHP 4, PHP 5)

is_array -- Verifica se una variabile è un array

Descrizione

bool is_array ( mixed var )

Verifica se il valore dato è un array.

Elenco dei parametri

var: Variabile da verificare.

Valori restituiti

Restituisce TRUE se var è una matrice, FALSE in caso contrario.

Esempi

Esempio 1. Verifica se una variabile è un array
<?php $yes = array('this', 'is', 'an array'); echo is_array($yes) ? 'Array' : 'not an Array'; echo "\n"; $no = 'this is a string'; echo is_array($no) ? 'Array' : 'not an Array'; ?>
Il precedente esempio visualizzerà:
Array not an Array

Vedere anche:

is_int()

is_bool

(PHP 4, PHP 5)

is_bool -- Verifica se una variabile è di tipo boolean

Descrizione

bool is_bool ( mixed var )

Verifica se la variabile data sia di tipo boolean

Elenco dei parametri

var: La variabile da valutare.

Valori restituiti

Restituisce TRUE se var è di tipo boolean, FALSE in caso contrario.

Esempi

Esempio 1. Esempi di is_bool()
<?php $a = false; $b = 0; // Poichè $a è booleana, questa è vera if (is_bool($a)) { echo "Yes, this is a boolean"; } // Poichè $b non è booleana, questa non è vera if (is_bool($b)) { echo "Yes, this is a boolean"; } ?>

Vedere anche:

is_int()

is_callable

(PHP 4 >= 4.0.6, PHP 5)

is_callable -- Verifica se il contenuto dell'argomento può essere eseguito come funzione

Descrizione

bool is_callable ( mixed var [, bool syntax_only [, string &callable_name]] )

Verifica che il contenuto di una funzione possa essere richiamato come una funzione. Questa verifica può essere eseguita su una semplice variabile contenente il nome di una funzione valida, oppure su un array contenente il nome di un oggetto ed il nome di una funzione

Il parametro var può essere sia il nome di una funzione sia un oggetto ed il nome del metodo nell'oggetto, tipo
array( $SomeObject, 'MethodName' )

Se il parametro syntax_only è impostato a TRUE la funzione eseguirà un controllo sulla validità del parametro var. La funzione scarterà variabili non stringhe o che non hanno la struttura per essere callback validi. L'unica struttura valida presuppone di avere solo 2 righe: una stringa con il nome dell'oggetto, una seconda riga con il nome del metodo.

Il terzo parametro callable_name contiene il "callable name". Nell'esempio che segue contiene "someClass:someMethod". Si noti che, nonostante someClass::SomeMethod() implichi il richiamo ad un metodo statico, questo non è il caso.

<?php
//  Come verificare se una variabile può essere eseguita
//  come funzione..

//
//  Semplice variabile contenente una funzione
//

function unaFunzione() 
{
}

$functionVariable = 'unaFunzione';

var_dump(is_callable( $functionVariable, false, $callable_name ));  // bool(true)

echo $callable_name, "\n";  // unaFunzione

//
//  Array contenente un metodo
//

class unaClasse {

  function unMetodo() 
  {
  }

}

$anObject = new unaClasse();
$methodVariable = array($anObject, 'unMetodo' );
var_dump(is_callable($methodVariable, true, $callable_name ));  //  bool(true)
echo $callable_name, "\n";  //  unaClasse:unMetodo
?>

is_double

(PHP 3, PHP 4, PHP 5)

is_double -- Alias di is_float()

Descrizione

This function is an alias of: is_float().

is_float

(PHP 3, PHP 4, PHP 5)

is_float -- Verifica se una variabile è di tipo float (decimale a virgola mobile)

Descrizione

bool is_float ( mixed var )

Verifica se una variabile è di tipo float (decimale a virgola mobile).

Nota: Per verificare se una variabile è un numero oppure una stringa numerica (come le variabili dei form, che sono sempre stringhe) occorre usare la funzione is_numeric().

Elenco dei parametri

var: La variabile da valutare.

Valori restituiti

Questa funzione restituisce TRUE se var è di tipo float, FALSE in caso contrario.

Vedere anche:

is_bool()

is_int()

is_int

(PHP 3, PHP 4, PHP 5)

is_int -- Verifica se una variabile è di tipo integer

Descrizione

bool is_int ( mixed var )

Verifica che la variabile data sia di tipo integer

Nota: Per verificare se una variabile è un numero oppure una stringa numerica (come le variabili dei form, che sono sempre stringhe) occorre usare la funzione is_numeric().

Elenco dei parametri

var: La variabile da valutare.

Valori restituiti

Restituisce TRUE se var è di tipo integer, FALSE in caso contrario.

Vedere anche:

is_bool()

bool is_null ( mixed var )

Verifica che la variabile data sia di tipo NULL

Elenco dei parametri

var: La variabile da valutare.

Valori restituiti

Restituisce TRUE se var è di tipo null, FALSE in caso contrario.

Vedere anche:

The NULL type

is_bool()

is_int()

is_numeric

(PHP 4, PHP 5)

is_numeric -- Verifica se una variabile è un numero o una stringa numerica

Descrizione

bool is_numeric ( mixed var )

Verifica se una variabile è un numero o una stringa numerica.

Elenco dei parametri

var: La variabile da valutare.

Valori restituiti

Restituisce TRUE se var è un numero o una stringa numerica, FALSE in caso contrario.

Vedere anche:

is_bool()

is_null()

is_int()

is_object

(PHP 3, PHP 4, PHP 5)

is_object -- Verifica se una variabile è di tipo object

Descrizione

bool is_object ( mixed var )

Verifica se una variabile è di tipo object.

Elenco dei parametri

var: La variabile da valutare.

Valori restituiti

Restituisce TRUE se var è un di tipo object, FALSE in caso contrario.

Vedere anche:

is_bool()

is_int()

The resource-type documentation

is_real

(PHP 3, PHP 4, PHP 5)

is_real -- Alias di is_float()

Descrizione

This function is an alias of: is_float().

is_resource

(PHP 4, PHP 5)

is_resource -- Verifica se una variabile è una risorsa

Descrizione

bool is_resource ( mixed var )

Verifica se una data variabile sia di tipo risorsa.

Elenco dei parametri

var: La variabile da valutare.

Valori restituiti

Restituisce TRUE se la variabile individuata dal parametro var è di tipo resource, altrimenti restituisce FALSE.

Esempi

Esempio 1. Esempio di utilizzo di is_resource()
<?php $db_link = @mysql_connect('localhost', 'mysql_user', 'mysql_pass'); if (!is_resource($db_link)) { die('Can\'t connect : ' . mysql_error()); } ?>

Vedere anche:

get_resource_type()

is_scalar

(PHP 4 >= 4.0.5, PHP 5)

is_scalar -- Verifica se la variabile è di tipo scalare

Descrizione

bool is_scalar ( mixed var )

Verifica se la data variabile sia di tipo scalare

Le variabili scalari sono quelle contenenti valori di tipo integer, float, string oppure boolean. I tipi array, object e resource non sono scalari.

Nota: La funzione is_scalar() non considera il tipo resource come valore scalare, dato che il tipo resource è una tipologia di dato astratto che attualmente si basa su interi. Tuttavia non ci si può basare su questo tipo di implementazione, in futuro potrebbe cambiare.

Elenco dei parametri

var: La variabile da valutare.

Valori restituiti

Restituisce TRUE se la variabile indicata dal parametro var è di tipo scalare, in caso contrario restituisce FALSE.

Esempi

Esempio 1. Esempio di uso di is_scalar()
<?php function show_var($var) { if (is_scalar($var)) { echo $var; } else { var_dump($var); } } $pi = 3.1416; $proteins = array("hemoglobin", "cytochrome c oxidase", "ferredoxin"); show_var($pi); show_var($proteins) ?>
Il precedente esempio visualizzerà:
3.1416 array(3) { [0]=> string(10) "hemoglobin" [1]=> string(20) "cytochrome c oxidase" [2]=> string(10) "ferredoxin" }

Vedere anche:

is_int()

is_real()

is_bool()

is_string

(PHP 3, PHP 4, PHP 5)

is_string -- Verifica se una variabile sia una stringa

Descrizione

bool is_string ( mixed var )

Verifica se una data variabile sia una stringa.

Elenco dei parametri

var: La variabile da valutare.

Valori restituiti

Restituisce TRUE se var è di tipo string, FALSE in caso contrario.

Vedere anche:

is_int()

is_bool()

win32_start_service_ctrl_dispatcher()

isset

(PHP 3, PHP 4, PHP 5)

isset -- Verifica se una variabile è definita

Descrizione

bool isset ( mixed variabile [, ...] )

Restituisce TRUE se la variabile esiste; FALSE in caso contrario.

Se una variabile è stata cancellata con unset(), non potrà essere impostata. La funzione isset() restituirà FALSE se viene utilizzata per testare una variabile valorizzata a NULL. Inoltre occorre notare che il byte NULL ("\0") non equivale alla costante PHP NULL.

Attenzione: La funzione isset() lavora soltanto con variabili, il passaggio di qualsiasi altro tipo di parametro genera un errore di parsing. Per verificare se le costanti sono definite utilizzare la funzione defined().

<?php

$var = '';

// Questo test sarà TRUE pertanto sarà visualizzato il testo.
if (isset($var)) {
    echo "Questa variabile è valorizzata, pertanto scrivo.";
}

// Nel prossimo esempio useremo var_dump per visualizzare
// il valore restituito da isset().

$a = "test";
$b = "anothertest";

var_dump(isset($a));      // TRUE
var_dump(isset($a, $b)); // TRUE

unset ($a);

var_dump(isset($a));     // FALSE
var_dump(isset($a, $b)); // FALSE

$foo = NULL;
var_dump(isset($foo));   // FALSE

?>

Questo esempio utilizza gli elementi di un array:

<?php  

$a = array ('test' => 1, 'hello' => NULL);

var_dump(isset($a['test']));            // TRUE
var_dump(isset($a['foo']));             // FALSE
var_dump(isset($a['hello']));           // FALSE

// La chiave 'hello' vale NULL pertanto viene considerata non impostata.
// Se si desidera verificare l'esistenza di chiavi con valore NULL, usare:
var_dump(array_key_exists('hello', $a)); // TRUE

?>

Nota: Poichè questo è un costrutto del linguaggio e non una funzione, non può essere chiamato con le variabili funzione

Vedere anche empty(), unset(), defined(), la tabella di comparazione dei tipi, array_key_exists() e l'operatore di controllo degli errori @.

print_r

(PHP 4, PHP 5)

print_r -- Stampa informazioni relative al contenuto di una variabile in formato leggibile

Descrizione

bool print_r ( mixed expression [, bool return] )

Nota: Il parametro return è stato aggiunto in PHP 4.3.0.

Questa funzione stampa delle informazioni sul contenuto di una variabile in un formato facilmente leggibile. Se la variabile contiene una stringa, un intero o un numero decimale, il valore stesso viene visualizzato. Se la variabile contiene un array i valori vengono visualizzati in un formato che evidenzia le chiavi ed i relativi elementi. Una notazione simile viene utilizzata per gli oggetti. Le funzioni print_r() e var_export(), a differenza di var_dump(), visualizzano le proprietà protette e private degli oggetti di PHP 5.

Occorre ricordarsi che print_r() posiziona il puntatore dell'array alla fine. Pertanto utilizzare reset() per riportarsi all'inizio.

<pre>
<?php
    $a = array ('a' => 'apple', 'b' => 'banana', 'c' => array ('x','y','z'));
    print_r ($a);
?>
</pre>

Il precedente esempio visualizzerà:

<pre>
Array
(
    [a] => apple
    [b] => banana
    [c] => Array
        (
            [0] => x
            [1] => y
            [2] => z
        )
)
</pre>

Se si desidera catturare l'output di print_r(), occorre utilizzare il parametro return. Se questo viene impostato a TRUE, print_r() restituirà l'output anzichè visualizzarlo (come accade per default).

Esempio 1. Esempio dell'uso di return
<?php $b = array ('m' => 'monkey', 'foo' => 'bar', 'x' => array ('x', 'y', 'z')); $results = print_r($b, true); //$results ora contiene l'output di print_r ?>

Nota: Se occorre catturare l'output di print_r() con versioni di PHP precedenti alla 4.3.0, occorre utlizzare le funzioni di controllo dell'output.

Nota: Questa funzione continua all'infinito se riceve come parametro un vettore o un oggetto contenente un riferimento diretto od indiretto a se stesso oppure contenente ulteriori vettori o oggetti che a loro volta referenziano il padre o se stessi. Un caso evidente è print_r($GLOBALS), in quanto $GLOBALS è a sua volta una variabile globale e in quanto tale contiene una referenza a se stessa.

Vedere anche ob_start(), var_dump() e var_export().

serialize

(PHP 3 >= 3.0.5, PHP 4, PHP 5)

serialize -- Genera una versione archiviabile del valore

Descrizione

string serialize ( mixed value )

La funzione serialize() restituisce una stringa contenente un flusso di bytes rappresentante value che possa essere archiviato ovunque.

Questo può essere utile per archiviare o passare valori senza perdere il tipo e la struttura.

Per ottenere il valore dalla stringa serializzata, utilizzare la funzione unserialize(). La funzione serialize() gestisce tutti i tipi di variabili tranne il tipo resource. Possono essere elaborati da serialize() array che contengano riferimenti a se stessi. Saranno archiviati anche i riferimenti interni agli array e ai tipi object passati a serialize()

Quando si esegue la serializzazione di oggetti, il PHP cerca di eseguire la funzione __sleep() prima di cominciare la serializzazione. Questo permette all'oggetto di eseguire le ultime operazioni di chiusura prima di essere serializzato. Analogamente quando l'oggetto viene ripristinato la funzione unserialize() richiama la funzione membro __wakeup().

Nota: Questa funzione non gira correttamente sino alla versione 4.0.7.

Nota: Nella versione 3 di PHP si serializzano le proprietà dell'oggetto, ma non i metodi. Nella versione 4 questa limitazione è stata rimossa, pertanto possono essere recuperati sia le proprietà sia i metodi. Per maggiori informazioni vedere la sezione Serializzare oggetti in Oggetti e Classi.
Non è possibile serializzare gli oggetti predefiniti di PHP.

Esempio 1. Esempio di serialize()
<?php // L'array multi-dimensionale $session_data contiene le informazioni della sessione // per l'utente. Si userà serialize() per memorizzare le informazioni // all'interno di un database alla fine della richiesta.. $conn = odbc_connect("webdb", "php", "chicken"); $stmt = odbc_prepare($conn, "UPDATE sessions SET data = ? WHERE id = ?"); $sqldata = array (serialize($session_data), $PHP_AUTH_USER); if (!odbc_execute($stmt, &$sqldata)) { $stmt = odbc_prepare($conn, "INSERT INTO sessions (id, data) VALUES(?, ?)"); if (!odbc_execute($stmt, &$sqldata)) { /* Qualcosa è andato storto */ } } ?>

Vedere anche: unserialize().

settype

(PHP 3, PHP 4, PHP 5)

settype -- Definisce il tipo di una variabile

Descrizione

bool settype ( mixed &var, string type )

Setta il tipo della variabile var a type.

Valori possibili di type sono:

"boolean" (oppure, da PHP 4.2.0, "bool")
"integer" (uppure, da PHP 4.2.0, "int")
"float" (soltanto a partire dalla versione 4.2.0 di PHP, per le versioni precedenti usare "double", deprecated)
"string"
"array"
"object"
"null" (dalla versione PHP 4.2.0)

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempio 1. Esempio di utilizzo di settype()
<?php $foo = "5bar"; // string $bar = true; // boolean settype($foo, "integer"); // $foo ora è 5 (integer) settype($bar, "string"); // $bar ora è "1" (string) ?>

Vedere anche gettype(), Casting del tipo e Manipolazione del tipo.

strval

(PHP 3, PHP 4, PHP 5)

strval -- Restituisce il valore di una variabile interpretato come stringa

Descrizione

string strval ( mixed var )

Restituisce il valore di var interpretato come stringa. Per maggiori informazioni sulla conversione a stringa, vedere la documentazione relativa alle variabili di tipo string.

var può essere una qualsiasi variabile scalare. Non è possibile usare strval() con array o oggetti.

Vedere anche floatval(), intval(), settype() e Manipolazione del tipo.

unserialize

(PHP 3 >= 3.0.5, PHP 4, PHP 5)

unserialize -- Crea un valore PHP a partire da una rappresentazione archiviata

Descrizione

mixed unserialize ( string str )

La funzione unserialize() prende il formato serializzato di una variabile (vedere serialize()) e la riporta a valore PHP. La funzione restituisce il valore ottenuto, che può essere di tipo boolean, integer, float, string, array oppure object. Nel caso in cui la stringa passata non sia deserializzabile la funzione restituisce FALSE e genera un E_NOTICE.

Avvertimento

FALSE è restituito sia in caso di errore e sia in caso di de-serializzazione del valore FALSE. Questo caso particolare può essere intercettato confrontando str con serialize(false) o rilevando il E_NOTICE generato.

Direttiva unserialize_callback_func: E' possibile impostare una funzione di callback che possa essere richiamata se, durante la fase di deserializzazione, occorre istanziare una classe indefinita. (per evitare di ottenere un tipo object incompleto "__PHP_Incomplete_Class".) Per definire il parametro 'unserialize_callback_func' si può agire sul php.ini, o usare ini_set() oppure con .htaccess. Verrà utilizzata questa funzione ogni volta che occorre istanziare una classe indefinita. Per disabilitare questa opzione, lasciare vuota questa impostazione. Attenzione che la direttiva unserialize_callback_func è disponibile dalla versione 4.2.0 di PHP.

Se la variabile da ripristinare è un oggetto, dopo avere ricostruito l'oggetto, il PHP cercherà di eseguire la funzione membro __wakeup() (se esiste).
Esempio 1. Esempio di unserialize_callback_func.
<?php $serialized_object='O:1:"a":1:{s:5:"value";s:3:"100";}'; // direttiva unserialize_callback_func disponibile dalla versione 4.2.0 ini_set('unserialize_callback_func', 'mycallback'); // imposta la funzione di callback function mycallback($classname) { // semplicemente include un file contenente la definizione della classe // la variabile $classname indica di quale classe occorre la definizione } ?>

Nota: Nella versione 3 di PHP, i metodi non erano preservati durante la fase di deserializzazione di un oggetto. In PHP 4 questo limite è stato superato e possono essere recuperati sia metodi sia proprietà. Per maggiori informazioni vedere la sezione Serializzare oggetti in Classi e oggetti

Esempio 2. Esempio di uso di unserialize()
<?php // In quest esempio si usa unserialize() per caricare i dati di una sessione da un database // alla variabile $session_data. Questo esempio è complementare a quello illustrato // nella funzione <function>serialize</function>. $conn = odbc_connect("webdb", "php", "chicken"); $stmt = odbc_prepare($conn, "SELECT data FROM sessions WHERE id = ?"); $sqldata = array ($PHP_AUTH_USER); if (!odbc_execute($stmt, &$sqldata) || !odbc_fetch_into($stmt, &$tmp)) { // se odbc_execute o odbc_fetch_into hanno un errore si predispone un array vuoto $session_data = array(); } else { // ora abbiamo i dati serializzati in $tmp[0]. $session_data = unserialize($tmp[0]); if (!is_array($session_data)) { // qualcosa è andato storto, si predispone un array vuoto $session_data = array(); } } ?>

Vedere anche: serialize().

unset

(PHP 3, PHP 4, PHP 5)

unset -- Cancella una data variabile

Descrizione

void unset ( mixed var [, mixed var [, mixed ...]] )

unset() distrugge la variabile specificata. Occorre notare che in PHP 3 la funzione unset() restituiva sempre TRUE (in realtà era il valore 1). In PHP 4, invece, la funzione unset() non è più una vera funzione, ora è una istruzione. In questa veste non ritorna alcun valore, e cercare di ottenere un valore dalla funzione unset() produce un errore di parsing.

Esempio 1. Esempio di unset()
<?php // Distrugge una singola variabile unset($foo); // distrugge un singolo elemento di un array unset($bar['quux']); // distrugge più di una variabile unset($foo1, $foo2, $foo3); ?>

Il comportamento di unset() all'interno di una funzione può variare in funzione del tipo di variabile che si intende distruggere.

Se si applica unset() ad una variabile globale all'interno di una funzione, sarà distrutta solo la variabile locale. Nell'ambiente chiamante, la variabile manterrà il medesimo valore che aveva prima dell'uso di unset().

<?php
function destroy_foo()
{
    global $foo;
    unset($foo);
}

$foo = 'bar';
destroy_foo();
echo $foo;
?>

Il precedente esempio visualizzerà:

bar

Nel caso di una variabile PASSATA PER RIFERIMENTO ad una funzione, l'uso della funzione unset() distrugge solo la copia locale della variabile. Nell'ambiente chiamante, la variabile manterrà il medesimo valore che aveva prima dell'uso di unset().

<?php
function foo(&$bar) 
{
    unset($bar);
    $bar = "blah";
}

$bar = 'something';
echo "$bar\n";

foo($bar);
echo "$bar\n";
?>

Il precedente esempio visualizzerà:

something
something

Se si usa unset() su una variabile statica all'interno di una funzione, unset() cancella la variabile e tutti i suoi riferimenti.

<?php
function foo() 
{
    static $a;
    $a++;
    echo "$a\n";

    unset($a);
}

foo();
foo();
foo();
?>

Il precedente esempio visualizzerà:

1
2
3

Se si desidera cancellare una variabile globale dall'interno di una funzione, occorre usare unset() sull'array $GLOBALS nel seguente modo:

<?php
function foo() 
{
    unset($GLOBALS['bar']);
}

$bar = "something";
foo();
?>

Nota: Poichè questo è un costrutto del linguaggio e non una funzione, non può essere chiamato con le variabili funzione

Vedere anche isset() e empty().

var_dump

(PHP 3 >= 3.0.5, PHP 4, PHP 5)

var_dump -- Stampa delle informazioni relative ad una variabile

Descrizione

void var_dump ( mixed expression [, mixed expression [, ...]] )

Questa funzione visualizza delle informazioni strutturate riguardanti una espressione, tra cui il suo tipo e il suo valore. Gli array e gli oggetti sono attraversati in maniera ricorsiva e i valori indentati per evidenziare la struttura.

In PHP 5 soltanto le proprietà pubbliche, private e protette di un oggetto possono essere restituite.

Suggerimento: Come con qualsiasi cosa che invia il risultato direttamente al browser, è possibile utilizzare la funzione output-control per catturare l'uscita di questa funzione e salvarla - per esempio - in una stringa.

Elenco dei parametri

expression: La variabile che si desidera visualizzare.

Valori restituiti

No value is returned.

Esempi

Esempio 1. var_dump() example
<?php $a = array(1, 2, array("a", "b", "c")); var_dump($a); ?>
Il precedente esempio visualizzerà:
array(3) { [0]=> int(1) [1]=> int(2) [2]=> array(3) { [0]=> string(1) "a" [1]=> string(1) "b" [2]=> string(1) "c" } }
<?php $b = 3.1; $c = true; var_dump($b, $c); ?>
Il precedente esempio visualizzerà:
float(3.1) bool(true)

Vedere anche:

var_export()

print_r()

var_export

(PHP 4 >= 4.2.0, PHP 5)

var_export -- Visualizza o restituisce una variabile in formato stringa

Descrizione

mixed var_export ( mixed expression [, bool return] )

La funzione var_export() restituisce informazioni strutturate sulla data variabile. E' simile a var_dump() con una differenza: il valore restituito è codice PHP.

Elenco dei parametri

expression: La variabile che si desidera esportare.
return: Se utilizzato ed impostato a TRUE, la funzione var_export() restituisce la rappresentazione della variabile anzichè visualizzarla.

Valori restituiti

Restituisce la rappresentazione della variabile quando il parametro return viene impostato a TRUE. Altrimenti la funzione restituisce NULL.

Esempi

Esempio 1. Esempio di utilizzo di var_export()
<?php $a = array (1, 2, array ("a", "b", "c")); var_export($a); ?>
Il precedente esempio visualizzerà:
array ( 0 => 1, 1 => 2, 2 => array ( 0 => 'a', 1 => 'b', 2 => 'c', ), )
<?php $b = 3.1; $v = var_export($b, true); echo $v; ?>
Il precedente esempio visualizzerà:
3.1

Note

Nota: Le variabili di tipo resource, le matrici e gli oggetti contenenti oggetti non possono essere esportati da questa funzione.

Vedere anche:

var_dump()

print_r()

CLIV. Verisign Payflow Pro Functions

Introduzione

This extension allows you to process credit cards and other financial transactions using Verisign Payment Services, formerly known as Signio (http://www.verisign.com/products-services/payment-processing/online-payment/payflow-pro/index.html).

When using these functions, you may omit calls to pfpro_init() and pfpro_cleanup() as this extension will do so automatically if required. However the functions are still available in case you are processing a number of transactions and require fine control over the library. You may perform any number of transactions using pfpro_process() between the two.

These functions were added in PHP 4.0.2.

Nota: These functions only provide a link to Verisign Payment Services. Be sure to read the Payflow Pro Developers Guide for full details of the required parameters.

Nota: Questo modulo è stato spostato nel repository PECL e non sarà più rilascio con il PHP dalla versione 5.1.0.

Nota: Questo modulo non è disponibile su piattaforme Windows.

Requisiti

You will require the appropriate SDK for your platform, which may be downloaded from within the manager interface once you have registered.

Once you have downloaded the SDK you should copy the files from the lib directory of the distribution. Copy the header file pfpro.h to /usr/local/include and the library file libpfpro.so to /usr/local/lib.

Alternatively, you can extract the tarball from Verisign in one location, and reference it during build configuration with the --with-pfpro[=DIR] option:
Esempio 1. Explicit Configuration
tar -zxf pfpro_sunsparc.tar.gz -C /usr/local/ ./configure --with-pfpro=/usr/local/verisign/payflowpro/sunsparc

Nota: The last portion of the path specified in the example above, in this case sunsparc, will vary based on which architecture your Verisign SDK was built for.

Installazione

These functions are only available if PHP has been compiled with the --with-pfpro[=DIR] option.

Avvertimento

If you are planing to use this extension along with the OpenSSL extension or with ModSSL, you should compile this extension as shared: --with-pfpro=shared,/usr/local.

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

Tabella 1. Verisign Payflow Pro configuration options

Name	Default	Changeable	Changelog
pfpro.defaulthost/PFPRO_VERSION < 3	"test.signio.com"	PHP_INI_ALL
pfpro.defaulthost	"test-payflow.verisign.com"	PHP_INI_ALL	Available since PHP 4.0.2.
pfpro.defaultport	"443"	PHP_INI_ALL	Available since PHP 4.0.2.
pfpro.defaulttimeout	"30"	PHP_INI_ALL	Available since PHP 4.0.2.
pfpro.proxyaddress	""	PHP_INI_ALL	Available since PHP 4.0.2.
pfpro.proxyport	""	PHP_INI_ALL	Available since PHP 4.0.2.
pfpro.proxylogon	""	PHP_INI_ALL	Available since PHP 4.0.2.
pfpro.proxypassword	""	PHP_INI_ALL	Available since PHP 4.0.2.

Per maggiori dettagli sulle costanti PHP_INI_* vedere Appendice G.

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

Questa estensione non definisce alcuna costante.

Sommario
pfpro_cleanup -- Shuts down the Payflow Pro library
pfpro_init -- Initialises the Payflow Pro library
pfpro_process_raw -- Process a raw transaction with Payflow Pro
pfpro_process -- Process a transaction with Payflow Pro
pfpro_version -- Returns the version of the Payflow Pro software

pfpro_process_raw() processes a raw transaction string with Payflow Pro. You should really use pfpro_process() instead, as the encoding rules of these transactions are non-standard.

The first parameter in this case is a string containing the raw transaction request. All other parameters are the same as with pfpro_process(). The return value is a string containing the raw response.

Nota: Be sure to read the Payflow Pro Developers Guide for full details of the required parameters and encoding rules. You would be well advised to use pfpro_process() instead.

Esempio 1. Payflow Pro raw example

<?php

pfpro_init();

$response = pfpro_process_raw("USER=mylogin&PWD[5]=m&ndy&PARTNER=VeriSign&TRXTYPE=S&TENDER=C&AMT=1.50&ACCT=4111111111111111&EXPDATE=0904");

if (!$response) {
  die("Couldn't establish link to Verisign.\n");
}

echo "Verisign raw response was " . $response;

pfpro_cleanup();

?>

pfpro_process

(PHP 4 >= 4.0.2, PHP 5)

pfpro_process -- Process a transaction with Payflow Pro

Description

array pfpro_process ( array parameters [, string address [, int port [, int timeout [, string proxy_address [, int proxy_port [, string proxy_logon [, string proxy_password]]]]]]] )

Returns: An associative array containing the response

pfpro_process() processes a transaction with Payflow Pro. The first parameter is an associative array containing keys and values that will be encoded and passed to the processor.

The second parameter is optional and specifies the host to connect to. By default this is "test.signio.com", so you will certainly want to change this to "connect.signio.com" in order to process live transactions.

The third parameter specifies the port to connect on. It defaults to 443, the standard SSL port.

The fourth parameter specifies the timeout to be used, in seconds. This defaults to 30 seconds. Note that this timeout appears to only begin once a link to the processor has been established and so your script could potentially continue for a very long time in the event of DNS or network problems.

The fifth parameter, if required, specifies the hostname of your SSL proxy. The sixth parameter specifies the port to use.

The seventh and eighth parameters specify the logon identity and password to use on the proxy.

The function returns an associative array of the keys and values in the response.

Nota: Be sure to read the Payflow Pro Developers Guide for full details of the required parameters.

Esempio 1. Payflow Pro example

<?php

pfpro_init();

$transaction = array('USER'    => 'mylogin',
                     'PWD'     => 'mypassword',
                     'PARTNER' => 'VeriSign',
                     'TRXTYPE' => 'S',
                     'TENDER'  => 'C',
                     'AMT'     => 1.50,
                     'ACCT'    => '4111111111111111',
                     'EXPDATE' => '0904'
                    );

$response = pfpro_process($transaction);

if (!$response) {
  die("Couldn't establish link to Verisign.\n");
}

echo "Verisign response code was " . $response['RESULT'];
echo ", which means: " . $response['RESPMSG'] . "\n";

echo "\nThe transaction request: ";
print_r($transaction);

echo "\nThe response: ";
print_r($response);

pfpro_cleanup();

?>

pfpro_version

(PHP 4 >= 4.0.2, PHP 5)

pfpro_version -- Returns the version of the Payflow Pro software

Description

string pfpro_version ( void )

pfpro_version() returns the version string of the Payflow Pro library. At the time of writing, this was L211.

CLV. Funzioni vpopmail

Introduzione

Avvertimento

Questo modulo è stato spostato dalla versione 4.3.0 di PHP ed ora è disponibile sotto PECL.

Installazione

In PHP 4, queste funzioni sono disponibili soltanto se il PHP viene configurato con --with-vpopmail[=DIR].

Sommario
vpopmail_add_alias_domain_ex -- Aggiunge un alias ad un esistente dominio virtuale
vpopmail_add_alias_domain -- Aggiunge un alias per un dominio virtuale
vpopmail_add_domain_ex -- Aggiunge un nuovo dominio virtuale
vpopmail_add_domain -- Aggiunge un nuovo dominio virtuale
vpopmail_add_user -- Aggiunge un nuovo utente al dominio virtuale specificato
vpopmail_alias_add -- Inserisce un alias virtuale
vpopmail_alias_del_domain -- Elimina tutti gli alias virtuali di un dominio
vpopmail_alias_del -- Elimina tutti gli alias virtuali di un utente
vpopmail_alias_get_all -- Riceve tutte le linee di un alias per un dominio
vpopmail_alias_get -- Riceve tutte le linee di un alias per un dominio
vpopmail_auth_user -- Tenta di validare un nome utente/dominio/password
vpopmail_del_domain_ex -- Elimina un dominio virtuale
vpopmail_del_domain -- Elimina un dominio virtuale
vpopmail_del_user -- Elimina un utente da un dominio virtuale
vpopmail_error -- Riceve il messaggio testuale dell'ultimo errore di vpopmail
vpopmail_passwd -- Cambia la password virtuale ad un utente
vpopmail_set_user_quota -- Imposta la quota ad un utente virtuale

CLVI. Funzioni W32api

Introduzione

Questa è una generica API verso le DLL. In origine fu scritta per consentire l'accesso alle API Win32 dal PHP, sebbene si possa anche accedere a funzioni esportate da altre DLL.

Attualmente i tipi di dati supportati dal modulo sono i generici tipi PHP (strings, booleans, floats, integers e null) e i tipi definiti dall'utente tramite w32api_deftype().

Nota: Questo modulo è stato spostato nel repository PECL e non sarà più rilascio con il PHP dalla versione 5.1.0.

Avvertimento

Requisiti

Questo modulo gira solo su sistemi Windows.

Installazione

Non è necessaria nessuna installazione per usare queste funzioni, esse fanno parte del core di PHP.

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Tipi di risorse

Questo modulo definisce un solo tipo di risorsa utilizzata per i tipi di dati definiti dall'utente. Il nome i questa risorsa è "dynaparm".

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

DC_MICROSOFT (integer)
DC_BORLAND (integer)
DC_CALL_CDECL (integer)
DC_CALL_STD (integer)
DC_RETVAL_MATH4 (integer)
DC_RETVAL_MATH8 (integer)
DC_CALL_STD_BO (integer)
DC_CALL_STD_MS (integer)
DC_CALL_STD_M8 (integer)
DC_FLAG_ARGPTR (integer)

Esempi

Nel seguente esempio si ottiene da quanto tempo il sistema è attivo ed il risultato viene visualizzato in una finestra.

Esempio 1. Ottenere il tempo di attività e visualizzarlo in una finestra

<?php
// Definizione delle costanti richieste, dati ottenuti da
// Visual Studio/Tools/Winapi/WIN32API.txt
define("MB_OK", 0);
 
// Carico il modulo
dl("php_w32api.dll");
 
// Registrazione della funzione GetTickCount da kernel32.dll
w32api_register_function("kernel32.dll",
                         "GetTickCount",
                         "long");
 
// Registrazione della funzione MessageBoxA da User32.dll
w32api_register_function("User32.dll",
                         "MessageBoxA",
                         "long");
 
// Ottiene il dato cercato
$ticks = GetTickCount();
 
// Converte in formato umano
$secs  = floor($ticks / 1000);
$mins  = floor($secs / 60);
$hours = floor($mins / 60);
 
$str = sprintf("You have been using your computer for:" .
                "\r\n %d Milliseconds, or \r\n %d Seconds" .
                "or \r\n %d mins or\r\n %d hours %d mins.",
                $ticks,
                $secs,
                $mins,
                $hours,
                $mins - ($hours*60));
	 
// Visualizza la finestra con il bottone di OK
MessageBoxA(NULL,
            $str,
            "Uptime Information",
            MB_OK);
?>

Sommario
w32api_deftype -- ...) Definisce un tipo per l'uso con altre w32api_functions
w32api_init_dtype -- Crea un'istanza ai tipi di dati typename e li riempie con i valori forniti
w32api_invoke_function -- ....) Invoca la funzione funcname con gli argomenti passati dopo il nome della funzione
w32api_register_function -- Registra la funzione function_name dalla libreria con PHP
w32api_set_call_method -- Imposta il metodo di chiamata usato

CLVII. WDDX Functions

Introduzione

These functions are intended for work with WDDX.

Requisiti

In order to use WDDX, you will need to install the expat library (which comes with Apache 1.3.7 or higher).

Installazione

After installing expat compile PHP with --enable-wddx.

La versione per Windows di PHP ha già compilato il supporto per questo modulo. Non occorre caricare alcun modulo addizionale per potere utilizzare queste funzioni.

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

Questa estensione non definisce alcuna costante.

Esempi

All the functions that serialize variables use the first element of an array to determine whether the array is to be serialized into an array or structure. If the first element has string key, then it is serialized into a structure, otherwise, into an array.

Esempio 1. Serializing a single value with WDDX

<?php
echo wddx_serialize_value("PHP to WDDX packet example", "PHP packet");
?>

This example will produce:

<wddxPacket version='1.0'><header comment='PHP packet'/><data>
<string>PHP to WDDX packet example</string></data></wddxPacket>

Esempio 2. Using incremental packets with WDDX

<?php
$pi = 3.1415926;
$packet_id = wddx_packet_start("PHP");
wddx_add_vars($packet_id, "pi");

/* Suppose $cities came from database */
$cities = array("Austin", "Novato", "Seattle");
wddx_add_vars($packet_id, "cities");

$packet = wddx_packet_end($packet_id);
echo $packet;
?>

This example will produce:

<wddxPacket version='1.0'><header comment='PHP'/><data><struct>
<var name='pi'><number>3.1415926</number></var><var name='cities'>
<array length='3'><string>Austin</string><string>Novato</string>
<string>Seattle</string></array></var></struct></data></wddxPacket>

Nota: If you want to serialize non-ASCII characters you have to convert your data to UTF-8 first (see utf8_encode() and iconv()).

Sommario
wddx_add_vars -- Add variables to a WDDX packet with the specified ID
wddx_deserialize -- Alias di wddx_unserialize()
wddx_packet_end -- Ends a WDDX packet with the specified ID
wddx_packet_start -- Starts a new WDDX packet with structure inside it
wddx_serialize_value -- Serialize a single value into a WDDX packet
wddx_serialize_vars -- Serialize variables into a WDDX packet
wddx_unserialize -- Unserializes a WDDX packet

wddx_add_vars

(PHP 3 >= 3.0.7, PHP 4, PHP 5)

wddx_add_vars -- Add variables to a WDDX packet with the specified ID

Description

bool wddx_add_vars ( int packet_id, mixed name_var [, mixed ...] )

wddx_add_vars() is used to serialize passed variables and add the result to the packet specified by the packet_id. The variables to be serialized are specified in exactly the same way as wddx_serialize_vars().

wddx_deserialize

(PHP 3 >= 3.0.7, PHP 4, PHP 5)

wddx_deserialize -- Alias di wddx_unserialize()

string wddx_serialize_vars ( mixed var_name [, mixed ...] )

wddx_serialize_vars() is used to create a WDDX packet with a structure that contains the serialized representation of the passed variables.

wddx_serialize_vars() takes a variable number of arguments, each of which can be either a string naming a variable or an array containing strings naming the variables or another array, etc.

Esempio 1. wddx_serialize_vars() example
<?php $a = 1; $b = 5.5; $c = array("blue", "orange", "violet"); $d = "colors"; $clvars = array("c", "d"); echo wddx_serialize_vars("a", "b", $clvars); ?>

The above example will produce:
<wddxPacket version='1.0'><header/><data><struct><var name='a'><number>1</number></var> <var name='b'><number>5.5</number></var><var name='c'><array length='3'> <string>blue</string><string>orange</string><string>violet</string></array></var> <var name='d'><string>colors</string></var></struct></data></wddxPacket>

wddx_unserialize

(PHP 3 >= 3.0.7, PHP 5 CVS only)

wddx_unserialize -- Unserializes a WDDX packet

Description

mixed wddx_unserialize ( string packet )

wddx_unserialize() takes a packet string and unserializes it. It returns the result which can be string, number, or array. Note that structures are unserialized into associative arrays.

CLVIII. win32service Functions

Introduzione

The win32service extension is a Windows specific extension that allows PHP to communicate with the Service Control Manager to start, stop, register and unregister services, and even allows your PHP scripts to run as a service.

Requisiti

Windows NT, Windows 2000, Windows XP or Windows Server 2003. Any version of windows derived from Windows NT should be compatible.

Installazione

Installing from PECL

You can download php_win32service.dll from http://snaps.php.net/win32/. Choose the PECL_X_X folder that matches you PHP version.
Copy the php_win32service.dll into your extension_dir.
Load the extension from your php.ini
extension=php_win32service.dll

Esempi

Esempio 1. Registering a PHP script to run as a service
<?php win32_create_service(array( 'service' => 'dummyphp', # the name of your service 'display' => 'sample dummy PHP service', # description 'params' => 'c:\path\to\script.php run', # path to the script and parameters )); ?>

Esempio 2. Unregistering a service
<?php win32_delete_service('dummyphp'); ?>

Esempio 3. Running as a service
<?php if ($argv[1] == 'run') { win32_start_service_ctrl_dispatcher('dummyphp'); while (WIN32_SERVICE_CONTROL_STOP != win32_get_last_control_message()) { # do your work here. # try not to take up more than 30 seconds before going around the loop # again } } ?>

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

WIN32_SERVICE_CONTROL_CONTINUE (integer)
WIN32_SERVICE_CONTROL_INTERROGATE (integer)
WIN32_SERVICE_CONTROL_PAUSE (integer)
WIN32_SERVICE_CONTROL_STOP (integer)
WIN32_SERVICE_CONTROL_HARDWAREPROFILECHANGE (integer)
WIN32_SERVICE_CONTROL_POWEREVENT (integer)
WIN32_SERVICE_CONTROL_SESSIONCHANGE (integer)
WIN32_ERROR_CALL_NOT_IMPLEMENTED (integer)
WIN32_NO_ERROR (integer)
WIN32_SERVICE_RUNNING (integer)
WIN32_SERVICE_STOPPED (integer)
WIN32_SERVICE_STOP_PENDING (integer)
WIN32_SERVICE_WIN32_OWN_PROCESS (integer)
WIN32_SERVICE_INTERACTIVE_PROCESS (integer)
WIN32_SERVICE_STOPPED (integer)
WIN32_SERVICE_START_PENDING (integer)
WIN32_SERVICE_STOP_PENDING (integer)
WIN32_SERVICE_RUNNING (integer)
WIN32_SERVICE_CONTINUE_PENDING (integer)
WIN32_SERVICE_PAUSE_PENDING (integer)
WIN32_SERVICE_PAUSED (integer)
WIN32_SERVICE_ACCEPT_NETBINDCHANGE (integer)
WIN32_SERVICE_ACCEPT_PARAMCHANGE (integer)
WIN32_SERVICE_ACCEPT_PAUSE_CONTINUE (integer)
WIN32_SERVICE_ACCEPT_SHUTDOWN (integer)
WIN32_SERVICE_ACCEPT_STOP (integer)
WIN32_SERVICE_ACCEPT_HARDWAREPROFILECHANGE (integer)
WIN32_SERVICE_ACCEPT_POWEREVENT (integer)
WIN32_SERVICE_ACCEPT_SESSIONCHANGE (integer)
WIN32_SERVICE_FILE_SYSTEM_DRIVER (integer)
WIN32_SERVICE_KERNEL_DRIVER (integer)
WIN32_SERVICE_WIN32_SHARE_PROCESS (integer)
WIN32_SERVICE_RUNS_IN_SYSTEM_PROCESS (integer)

Sommario
win32_create_service -- Creates a new service entry in the SCM database
win32_delete_service -- Deletes a service entry from the SCM database
win32_get_last_control_message -- Returns the last control message that was sent to this service
win32_query_service_status -- Queries the status of a service
win32_set_service_status -- Update the service status
win32_start_service_ctrl_dispatcher -- Registers the script with the SCM, so that it can act as the service with the given name
win32_start_service -- Starts a service
win32_stop_service -- Stops a service

win32_create_service

(PECL)

win32_create_service -- Creates a new service entry in the SCM database

Descrizione

long win32_create_service ( array details [, string machine] )

Elenco dei parametri

details

An array of service details:

service: The short name of the service. This is the name that you will use to control the service using the net command. The service must be unique (no two services can share the same name), and, ideally, should avoid having spaces in the name.
display: The display name of the service. This is the name that you will see in the Services Applet.
user: The name of the user account under which you want the service to run. If omitted, the service will run as the LocalSystem account. If the username is specified, you must also provide a password.
password: The password that corresponds to the user.
path: The full path to the executable module that will be launched when the service is started. If omitted, the path to the current PHP process will be used.
params: Command line parameters to pass to the service when it starts. If you want to run a PHP script as the service, then the first parameter should be the full path to the PHP script that you intend to run.
load_order: Controls the load_order. This is not yet fully supported.
svc_type: Sets the service type. If omitted, the default value is WIN32_SERVICE_WIN32_OWN_PROCESS. Don't change this unless you know what you're doing.
start_type: Specifies how the service should be started. The default is WIN32_SERVICE_AUTO_START which means the the service will be launched when the machine starts up.
error_control: Informs the SCM what it should do when it detects a problem with the service. The default is WIN32_SERVER_ERROR_IGNORE. Changing this value is not yet fully supported.

machine

The optional machine name on which you want to create a service. If omitted, it will use the local machine.

Valori restituiti

Returns TRUE on success, otherwise returns a win32 error code.

Esempi

Esempio 1. A win32_create_service() example
Any text that describes the purpose of the example, or what goes on in the example should go here (inside the
<?php $x = win32_create_service(array( 'service' => 'dummyphp', 'display' => 'sample dummy PHP service', 'params' => __FILE__ . ' run', )); debug_zval_dump($x); ?>

Vedere anche:

win32_delete_service()

win32_delete_service

(PECL)

win32_delete_service -- Deletes a service entry from the SCM database

Descrizione

long win32_delete_service ( string servicename [, string machine] )

Attempts to delete a service from the SCM database. Administrative privileges are required for this to succeed.

This function really just marks the service for deletion. If other processes (such as the Services Applet) are open, then the deletion will be deferred until those applications are closed. If a service is marked for deletion, further attempts to delete it will fail, and attempts to create a new service with that name will also fail.

Elenco dei parametri

servicename: The short name of the service.
machine: The optional machine name. If omitted, the local machine will be used.

Valori restituiti

Returns TRUE on success, or a win32 error code on failure.

Esempi

Esempio 1. A win32_delete_service() example
Deletes the dummyphp service.
<?php win32_delete_service('dummyphp'); ?>

win32_get_last_control_message

(PECL)

win32_get_last_control_message -- Returns the last control message that was sent to this service

Descrizione

long win32_get_last_control_message ( void )

Returns the control code that was last sent to this service process. When running as a service you should periodically check this to determine if your service needs to stop running.

Valori restituiti

Returns a control constant; one of WIN32_SERVICE_CONTROL_CONTINUE, WIN32_SERVICE_CONTROL_INTERROGATE, WIN32_SERVICE_CONTROL_PAUSE, WIN32_SERVICE_CONTROL_STOP, WIN32_SERVICE_CONTROL_HARDWAREPROFILECHANGE, WIN32_SERVICE_CONTROL_POWEREVENT, WIN32_SERVICE_CONTROL_SESSIONCHANGE.

Vedere anche:

win32_query_service_status

(PECL)

win32_query_service_status -- Queries the status of a service

Descrizione

mixed win32_query_service_status ( string servicename [, string machine] )

Queries the current status for a service, returning an array of information.

Elenco dei parametri

servicename: The short name of the service.
machine: The optional machine name. If omitted, the local machine will be used.

Valori restituiti

Returns FALSE on failure, otherwise returns an array consisting of the following information:

ServiceType: The dwServiceType.
CurrentState: The dwCurrentState.
ControlsAccepted: Which service controls are accepted by the service.
Win32ExitCode: If the service exited, the return code from the process.
ServiceSpecificExitCode: If the service exited with an error condition, the service specific code that is logged in the event log is visible here.
CheckPoint: If the service is shutting down, holds the current check point number. This is used by the SCM as a kind of heart-beat to detect a wedged service process. The value of the check point is best interpreted in conjunction with the WaitHint value.
WaitHint: If the service is shutting down it will set WaitHint to a checkpoint value that will indicate 100% completion. This can be used to implement a progress indicator.
ProcessId: The windows process identifier. If 0, the process is not running.
ServiceFlags: The dwServiceFlags.

win32_set_service_status

(PECL)

win32_set_service_status -- Update the service status

Descrizione

bool win32_set_service_status ( int status )

Informs the SCM of the current status of a running service. This call is only valid for a running service process.

Elenco dei parametri

status: The service status code, one of WIN32_SERVICE_RUNNING, WIN32_SERVICE_STOPPED, WIN32_SERVICE_STOP_PENDING, WIN32_SERVICE_START_PENDING, WIN32_SERVICE_CONTINUE_PENDING, WIN32_SERVICE_PAUSE_PENDING, WIN32_SERVICE_PAUSED.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

win32_start_service_ctrl_dispatcher()

win32_start_service_ctrl_dispatcher

(PECL)

win32_start_service_ctrl_dispatcher -- Registers the script with the SCM, so that it can act as the service with the given name

Descrizione

bool win32_start_service_ctrl_dispatcher ( string name )

When launched via the Service Control Manager, a service process is required to "check-in" with it to establish service monitoring and communication facilities. This function performs the check-in by spawning a thread to handle the lower-level communication with the service control manager.

Once started, the service process should continue to check-in with the service control manager so that it can determine if it should terminate. This is achieved by periodically calling win32_get_last_control_message() and handling the return code appropriately.

Elenco dei parametri

name: The short-name of the service, as registered by win32_create_service().

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 1. A win32_start_service_ctrl_dispatcher() example
Any text that describes the purpose of the example, or what goes on in the example should go here (inside the
<?php if (!win32_start_service_ctrl_dispatcher('dummyphp')) { die("I'm probably not running under the service control manager"); } while (WIN32_SERVICE_CONTROL_STOP != win32_get_last_control_message()) { # do some work here, trying not to take more than around 30 seconds # before coming back into the loop again } ?>

Vedere anche:

win32_get_last_control_message()

win32_start_service

(PECL)

win32_start_service -- Starts a service

Descrizione

long win32_start_service ( string servicename [, string machine] )

Attempts to start the named service. Usually requires administrative privileges.

Elenco dei parametri

servicename: The short name of the service.
machine: Optional machine name. If omitted, the local machine is used.

Valori restituiti

Returns WIN32_NO_ERROR on success, or some other win32 error code on failure.

Vedere anche:

win32_stop_service()

win32_stop_service

(PECL)

win32_stop_service -- Stops a service

Descrizione

long win32_stop_service ( string servicename [, string machine] )

Stops a named service. Requires administrative privileges.

Elenco dei parametri

servicename: The short name of the service.
machine: Optional machine name. If omitted, the local machine is used.

Valori restituiti

Returns WIN32_NO_ERROR on success, or a win32 error code on failure.

Vedere anche:

win32_start_service()

CLIX. xattr Functions

Introduzione

The xattr extension allows for the manipulation of extended attributes on a filesystem.

Requisiti

To use xattr, you will need libattr installed. It is available at http://oss.sgi.com/projects/xfs/.

Nota: 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.

Installazione

xattr is currently available through PECL http://pecl.php.net/package/xattr.

If PEAR is available on your *nix-like system you can use the pear installer to install the xattr extension, by the following command: pear -v install xattr.

You can always download the tar.gz package and install xattr by hand:
Esempio 1. xattr install by hand
gunzip xattr-xxx.tgz tar -xvf xattr-xxx.tar cd xattr-xxx phpize ./configure && make && make install

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

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.

Sommario
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

xattr_get

(PECL)

xattr_get -- Get an extended attribute

Descrizione

string xattr_get ( string filename, string name [, int flags] )

This function gets the value of an extended attribute of a file.

Extended attributes have two different namespaces: user and root namespace. User namespace is available for all users while root namespace is available only for user with root privileges. xattr operates on user namespace by default, but you can change that using flags argument.

Elenco dei parametri

filename

The file from which we get the attribute.

name

The name of the attribute.

flags

Tabella 1. Supported xattr flags

`XATTR_DONTFOLLOW`	Do not follow the symbolic link but operate on symbolic link itself.
`XATTR_ROOT`	Set attribute in root (trusted) namespace. Requires root privileges.

Valori restituiti

Returns a string containing the value or FALSE if the attribute doesn't exist.

Esempi

Esempio 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 ... */ ?>

Vedere anche:

xattr_list()

xattr_set()

xattr_remove()

xattr_list

(PECL)

xattr_list -- Get a list of extended attributes

Descrizione

array xattr_list ( string filename [, int flags] )

This functions gets a list of names of extended attributes of a file.

Elenco dei parametri

filename

The path of the file.

flags

Tabella 1. Supported xattr flags

`XATTR_DONTFOLLOW`	Do not follow the symbolic link but operate on symbolic link itself.
`XATTR_ROOT`	Set attribute in root (trusted) namespace. Requires root privileges.

Valori restituiti

This function returns an array with names of extended attributes.

Esempi

Esempio 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); } ?>

Vedere anche:

xattr_remove

(PECL)

xattr_remove -- Remove an extended attribute

Descrizione

bool xattr_remove ( string filename, string name [, int flags] )

This function removes an extended attribute of a file.

Elenco dei parametri

filename

The file from which we remove the attribute.

name

The name of the attribute to remove.

flags

Tabella 1. Supported xattr flags

`XATTR_DONTFOLLOW`	Do not follow the symbolic link but operate on symbolic link itself.
`XATTR_ROOT`	Set attribute in root (trusted) namespace. Requires root privileges.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 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); } ?>

Vedere anche:

xattr_list()

xattr_set()

xattr_set

(PECL)

xattr_set -- Set an extended attribute

Descrizione

bool xattr_set ( string filename, string name, string value [, int flags] )

This function sets the value of an extended attribute of a file.

Elenco dei parametri

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 flags parameter.

value

The value of the attribute.

flags

Tabella 1. Supported xattr flags

`XATTR_CREATE`	Function will fail if extended attribute already exists.
`XATTR_REPLACE`	Function will fail if extended attribute doesn't exist.
`XATTR_DONTFOLLOW`	Do not follow the symbolic link but operate on symbolic link itself.
`XATTR_ROOT`	Set attribute in root (trusted) namespace. Requires root privileges.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempi

Esempio 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')); ?>

Vedere anche:

xattr_remove()

xattr_supported

(PECL)

xattr_supported -- Check if filesystem supports extended attributes

Descrizione

bool xattr_supported ( string filename [, int flags] )

This functions checks if the filesystem holding the given file supports extended attributes. Read access to the file is required.

Elenco dei parametri

filename

The path of the tested file.

flags

Tabella 1. Supported xattr flags

XATTR_DONTFOLLOW Do not follow the symbolic link but operate on symbolic link itself.

Valori restituiti

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).

Esempi

Esempio 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 ... */ } ?>

Vedere anche:

XMLReader->getAttributeNo()

xattr_list()

CLX. xdiff Functions

Introduzione

xdiff extension creates and applies patches to both text and binary files.

Requisiti

To use xdiff, you will need libxdiff installed, available on the libxdiff homepage http://www.xmailserver.org/xdiff-lib.html.

Nota: You'll need at least libxdiff 0.7 for these functions to be aware of memory_limit.

Installazione

xdiff is currently available through PECL http://pecl.php.net/package/xdiff.

If PEAR is available on your *nix-like system you can use the pear installer to install the xdiff extension, by the following command: pear -v install xdiff.

You can always download the tar.gz package and install xdiff by hand:
Esempio 1. xdiff install by hand
gunzip xdiff-xxx.tgz tar -xvf xdiff-xxx.tar cd xdiff-xxx phpize ./configure && make && make install

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

XDIFF_PATCH_NORMAL (integer)
XDIFF_PATCH_REVERSE (integer)

Sommario
xdiff_file_diff_binary -- Make binary diff of two files
xdiff_file_diff -- Make unified diff of two files
xdiff_file_merge3 -- Merge 3 files into one
xdiff_file_patch_binary -- Patch a file with a binary diff
xdiff_file_patch -- Patch a file with an unified diff
xdiff_string_diff_binary -- Make binary diff of two strings
xdiff_string_diff -- Make unified diff of two strings
xdiff_string_merge3 -- Merge 3 strings into one
xdiff_string_patch_binary -- Patch a string with a binary diff
xdiff_string_patch -- Patch a string with an unified diff

xdiff_file_diff_binary

(PECL)

xdiff_file_diff_binary -- Make binary diff of two files

Description

bool xdiff_file_diff_binary ( string file1, string file2, string dest )

xdiff_file_diff_binary() makes binary diff of files file1 and file2 and stores result in file dest. This function works with both text and binary files. Resulting file is in binary format.

Nota: Both files will be loaded into memory so ensure that your memory_limit is set high enough.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempio 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');
?>

xdiff_file_diff

(PECL)

xdiff_file_diff -- Make unified diff of two files

Description

bool xdiff_file_diff ( string file1, string file2, string dest [, int context [, bool minimal]] )

xdiff_file_diff() makes unified diff of files file1 and file2 and stores result in file dest. context indicated how many lines of context you want to include in diff result. Set minimal to TRUE if you want to minimalize size of diff (can take a long time). Resulting file is human-readable.

Nota: This function doesn't work well with binary files. To make diff of binary files use xdiff_file_diff_binary().

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempio 1. xdiff_file_diff() example

The following code makes unified diff of two php files.

<?php
$old_version = 'my_script.php';
$new_version = 'my_new_script.php';

xdiff_file_diff($old_version, $new_version, 'my_script.diff', 2);
?>

xdiff_file_merge3

(PECL)

xdiff_file_merge3 -- Merge 3 files into one

Description

mixed xdiff_file_merge3 ( string file1, string file2, string file3, string dest )

xdiff_file_merge3() merges files file1, file2 and file3 into one and stores result in file dest.

Returns TRUE if merge was successful, string with rejected chunks if it was not or FALSE if an internal error happened.

Esempio 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_file_patch_binary -- Patch a file with a binary diff

Description

bool xdiff_file_patch_binary ( string file, string patch, string dest )

xdiff_file_patch_binary() patches file file with binary patch in file patch and stores result in file dest.

Nota: Both files (file and patch) will be loaded into memory so ensure that your memory_limit is set high enough.

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Esempio 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";
}

?>

xdiff_file_patch

(PECL)

xdiff_file_patch -- Patch a file with an unified diff

Description

mixed xdiff_file_patch ( string file, string patch, string dest [, int flags] )

xdiff_file_patch() patches file file with unified patch in file patch and stores result in file dest.

flags can be either XDIFF_PATCH_NORMAL (default mode, normal patch) or XDIFF_PATCH_REVERSE (reversed patch).

Returns FALSE if an internal error happened, string with rejected chunks of patch or TRUE if patch has been successfully applied.

Esempio 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;
}

?>

Esempio 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_string_diff_binary

(PECL)

xdiff_string_diff_binary -- Make binary diff of two strings

Description

string xdiff_string_diff_binary ( string str1, string str2 )

xdiff_string_diff_binary() makes binary diff of strings str1 and str2.

Returns string with result or FALSE if an internal error happened.

xdiff_string_diff

(PECL)

xdiff_string_diff -- Make unified diff of two strings

Description

string xdiff_string_diff ( string str1, string str2 [, int context [, bool minimal]] )

xdiff_string_diff() makes unified diff of strings str1 and str2. context indicated how many lines of context you want to include in diff result. Set minimal to TRUE if you want to minimalize size of diff (can take a long time).

Nota: This function doesn't work well with binary strings. To make diff of binary strings use xdiff_string_diff_binary().

Returns string with result or FALSE if an internal error happened.

Esempio 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;
}

?>

xdiff_string_merge3

(PECL)

xdiff_string_merge3 -- Merge 3 strings into one

Description

mixed xdiff_string_merge3 ( string str1, string str2, string str3 [, string &error] )

xdiff_string_merge3() merges strings str1, str2 and str3 into one.

If error is passed then rejected parts are stored inside this variable.

Returns merged string, FALSE if an internal error happened, or TRUE if merged string is empty.

xdiff_string_patch_binary

(PECL)

xdiff_string_patch_binary -- Patch a string with a binary diff

Description

string xdiff_string_patch_binary ( string str, string patch )

xdiff_string_patch_binary() patches string str with binary patch in string patch.

Returns a patched string.

xdiff_string_patch

(PECL)

xdiff_string_patch -- Patch a string with an unified diff

Description

string xdiff_string_patch ( string str, string patch [, int flags [, string &error]] )

xdiff_string_patch() patches string str with unified patch in string patch.

flags can be either XDIFF_PATCH_NORMAL (default mode, normal patch) or XDIFF_PATCH_REVERSE (reversed patch).

If error is passed then rejected parts are stored inside this variable.

Esempio 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;
}

?>

Returns a patched string.

CLXI. Funzioni relative al parser XML

Introduzione

XML (eXtensible Markup Language) è un formato utilizzato per l'interscambio di documenti strutturati sul Web. Questo è uno standard definito da The World Wide Web consortium (W3C). Maggiori informazioni su XML e le relative tecnologie possono essere reperite all'indirizzo http://www.w3.org/XML/.

Questo modulo del PHP offre il supporto del modulo expat di James Clark. Questo tool permette il parsing, ma non la validazione, di documenti XML. Sono supportati tre tipi di codifica di caratteri, supportati anche dal PHP:US-ASCII, ISO-8859-1 ed UTF-8. La codifica UTF-16 non è supportata.

Questo modulo permette di creare parser XML e di definire dei gestori per i vari eventi XML. Inoltre ogni singolo parser XML ha diversi parametri che possono essere configurati in base alle varie esigenze.

Requisiti

Di norma questo modulo utilizza un expat compat layer. Tuttavia si può utilizzare anche expat, che può essere reperito all'indirizzo http://www.jclark.com/xml/expat.html. Il Makefile fornito con expat, per default, non compila la libreria, occorre utilizzare le seguenti istruzioni per il comando make:
libexpat.a: $(OBJS) ar -rc $@ $(OBJS) ranlib $@
Il sorgente in formato package RPM può essere reperito all'indirizzo http://sourceforge.net/projects/expat/.

Installazione

Queste funzioni sono abilitate per default utilizzando le libreria expat fornita. Si può disabilitare il supporto XML utilizzando --disable-xml. Se si compila il PHP come modulo per Apache 1.3.9 o versioni successive, il PHP automaticamente utilizzerà la libreria expat di Apache. Se non si desidera utilizzare la libreria fornita, configurare il PHP con --with-expat-dir=DIR, dove DIR indica la directory in cui è installato expat.

La versione per Windows di PHP ha già compilato il supporto per questo modulo. Non occorre caricare alcun modulo addizionale per potere utilizzare queste funzioni.

Configurazione di Runtime

Questa estensione non definisce alcuna direttiva di configurazione in php.ini

Tipi di risorse

`xml`

La risorsa xml restituita da xml_parser_create() e xml_parser_create_ns() è un riferimento all'istanza del parser da utilizzarsi con le funzioni previste da questo modulo.

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

XML_ERROR_NONE (integer)
XML_ERROR_NO_MEMORY (integer)
XML_ERROR_SYNTAX (integer)
XML_ERROR_NO_ELEMENTS (integer)
XML_ERROR_INVALID_TOKEN (integer)
XML_ERROR_UNCLOSED_TOKEN (integer)
XML_ERROR_PARTIAL_CHAR (integer)
XML_ERROR_TAG_MISMATCH (integer)
XML_ERROR_DUPLICATE_ATTRIBUTE (integer)
XML_ERROR_JUNK_AFTER_DOC_ELEMENT (integer)
XML_ERROR_PARAM_ENTITY_REF (integer)
XML_ERROR_UNDEFINED_ENTITY (integer)
XML_ERROR_RECURSIVE_ENTITY_REF (integer)
XML_ERROR_ASYNC_ENTITY (integer)
XML_ERROR_BAD_CHAR_REF (integer)
XML_ERROR_BINARY_ENTITY_REF (integer)
XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF (integer)
XML_ERROR_MISPLACED_XML_PI (integer)
XML_ERROR_UNKNOWN_ENCODING (integer)
XML_ERROR_INCORRECT_ENCODING (integer)
XML_ERROR_UNCLOSED_CDATA_SECTION (integer)
XML_ERROR_EXTERNAL_ENTITY_HANDLING (integer)
XML_OPTION_CASE_FOLDING (integer)
XML_OPTION_TARGET_ENCODING (integer)
XML_OPTION_SKIP_TAGSTART (integer)
XML_OPTION_SKIP_WHITE (integer)

Gestori di eventi

I gestori di eventi XML definiti sono:

Tabella 1. Gestori XML supportati

Funzione PHP per attivare il gestore	Descrizione dell'evento
xml_set_element_handler()	L'evento 'Elemento' viene attivato quando il parser XML incontra i tag di apertura e chiusura. Esistono gestori separati per i tag di apertura e di chiusura.
xml_set_character_data_handler()	Sono dati tutti i contenuti dei documenti XML che non siano dei markup, compresi gli spazi tra i tag. Si noti che il parser XML non aggiunge ne rimuove spazi, è compito dell'applicazione decidere se gli spazi siano significativi o meno.
xml_set_processing_instruction_handler()	Ai programmatori PHP dovrebbe già essere familiare le istruzioni di processo (PIs). <?php ?> è un istruzione di processo dove `php` viene definito "PI target". La gestione di questi è specifica dell'applicazione, tranne che tutti i PI targets che iniziano con "XML", questi sono riservati.
xml_set_default_handler()	Tutto ciò che non rientra negli altri gestori ricade nel gestore di default. In questo gestore si ha elementi come la dichiarazione dei tipo documento.
xml_set_unparsed_entity_decl_handler()	Questo gestore viene richiamato per la gestione di entità non analizzate (NDATA).
xml_set_notation_decl_handler()	Questo gestore viene richiamato per la dichiarazione di una notazione.
xml_set_external_entity_ref_handler()	Questo gestore viene richiamato quando il parser XML incontra un riferimento ad una entità esterna analizzata. Questa può essere, ad esempio, un riferimento ad un file o ad un URL. Vedere esempio di entità esterne per una dimostrazione.

Case Folding

Le funzioni di gestione degli elementi possono ottenere i nomi dei propri elementi case-folded. Lo standard XML definisce il case-folding come "un processo applicato ad una sequenza di caratteri, nel quale quelli identificati come non-maiuscoli sono sostituiti dai corrispettivi caratteri maiuscoli". In altre parole, in XML il termine case-folding indica, semplicemente, la conversione a lettere maiuscole.

Per default, i nomi di tutti gli elementi passati alle funzioni di gestione sono case-folded. Questo comportamento può essere verificato e controllato nel parser XML rispettivamente con le funzioni xml_parser_get_option() e xml_parser_set_option().

Codici di errore

Vengono definite le seguenti costanti per i codici di errore XML (come restituito da xml_parse()):

XML_ERROR_NONE

XML_ERROR_NO_MEMORY

XML_ERROR_SYNTAX

XML_ERROR_NO_ELEMENTS

XML_ERROR_INVALID_TOKEN

XML_ERROR_UNCLOSED_TOKEN

XML_ERROR_PARTIAL_CHAR

XML_ERROR_TAG_MISMATCH

XML_ERROR_DUPLICATE_ATTRIBUTE

XML_ERROR_JUNK_AFTER_DOC_ELEMENT

XML_ERROR_PARAM_ENTITY_REF

XML_ERROR_UNDEFINED_ENTITY

XML_ERROR_RECURSIVE_ENTITY_REF

XML_ERROR_ASYNC_ENTITY

XML_ERROR_BAD_CHAR_REF

XML_ERROR_BINARY_ENTITY_REF

XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF

XML_ERROR_MISPLACED_XML_PI

XML_ERROR_UNKNOWN_ENCODING

XML_ERROR_INCORRECT_ENCODING

XML_ERROR_UNCLOSED_CDATA_SECTION

XML_ERROR_EXTERNAL_ENTITY_HANDLING

Codifica dei caratteri

L'estensione XML di PHP supporta il set di caratteri Unicode tramite differenti codifiche di caratteri. Esistono due tipi di codifiche di caratteri, source encoding e target encoding. Nella rappresentazione interna dei documenti il PHP utilizza sempre la codifica UTF-8.

La codifica del sorgente viene eseguita quando un documento XML viene analizzato. Durante la creazione di un parser XML, si può specificare la codifica del sorgente (questa codifica non potrà essere variata in seguito nel corso della vita del parser XML). Le codifiche supportate sono ISO-8859-1, US-ASCII e UTF-8. Le prime due sono codifiche a singolo byte, ciò significa che ciascun carattere è rappresentato da un byte singolo, mentre la codifica UTF-8 può rappresentare caratteri composti da un numero variabile di bit (fino a 21) usando da uno fino a quattro byte. La codifica del sorgente utilizzata per default dal PHP è ISO-8859-1.

La codifica per il destinatario viene eseguita quando il PHP passa i dati alle funzioni di gestione del XML. Quando viene creato un parser XML, la codifica per il destinatario viene posta uguale alla codifica del sorgente, ma ciò può essere variato. La codifica per il destinatario viene applicata ai caratteri dei dati, ai nomi dei tag e alle istruzioni di processamento.

Se il parser XML incontra caratteri esterni al range dei caratteri rappresentabili dalla codifica, restituirà un errore.

Se il PHP incontra nel documento analizzato dei caratteri che non è in grado di rappresentare con la codifica scelta per il destinatario, "degrada" il carattere problematico. Attaualmente ciò significa sostuire il carattere in questione con un punto interrogativo.

Esempi

Di seguito verranno illustrati alcuni esempi di script PHP per il parsing di documenti XML.

Esempio della struttura degli elementi XML

Il primo esempio visualizza, con indentazione, la struttura degli elementi di apertura di un documento.
Esempio 1. Visualizza la struttura degli elementi XML
<?php $file = "data.xml"; $depth = array(); function startElement($parser, $name, $attrs) { global $depth; for ($i = 0; $i < $depth[$parser]; $i++) { echo " "; } echo "$name\n"; $depth[$parser]++; } function endElement($parser, $name) { global $depth; $depth[$parser]--; } $xml_parser = xml_parser_create(); xml_set_element_handler($xml_parser, "startElement", "endElement"); if (!($fp = fopen($file, "r"))) { die("could not open XML input"); } while ($data = fread($fp, 4096)) { if (!xml_parse($xml_parser, $data, feof($fp))) { die(sprintf("XML error: %s at line %d", xml_error_string(xml_get_error_code($xml_parser)), xml_get_current_line_number($xml_parser))); } } xml_parser_free($xml_parser); ?>

Esempio di mappatura dei tag XML

Esempio 2. Conversione da XML a HTML
Il seguente esempio converte i tag di un documento XML in tag HTML. Gli elementi non trovati nella matrice dei tag saranno ignorati. Ovviamente questo esempio funziona solo con uno specifico tipo di documento XML:

<?php $file = "data.xml"; $map_array = array( "BOLD" => "B", "EMPHASIS" => "I", "LITERAL" => "TT" ); function startElement($parser, $name, $attrs) { global $map_array; if (isset($map_array[$name])) { echo "<$map_array[$name]>"; } } function endElement($parser, $name) { global $map_array; if (isset($map_array[$name])) { echo "</$map_array[$name]>"; } } function characterData($parser, $data) { echo $data; } $xml_parser = xml_parser_create(); // Si utilizza il case-folding per essere certi di trovare le tag in $map_array xml_parser_set_option($xml_parser, XML_OPTION_CASE_FOLDING, true); xml_set_element_handler($xml_parser, "startElement", "endElement"); xml_set_character_data_handler($xml_parser, "characterData"); if (!($fp = fopen($file, "r"))) { die("Non si riesce ad aprire il documento XML"); } while ($data = fread($fp, 4096)) { if (!xml_parse($xml_parser, $data, feof($fp))) { die(sprintf("Errore XML: %s alla linea %d", xml_error_string(xml_get_error_code($xml_parser)), xml_get_current_line_number($xml_parser))); } } xml_parser_free($xml_parser); ?>

Esempio di entità XML esterna

Questo esempio evidenzia il codice XML. Si illustrerà come utilizzare il riferimento ad entità esterne per includere ed analizzare altri documenti, sarà illustrato anche come processare le PI, ed il modo per determinare l'affidabilità del codice contenuto delle PI.

I documenti XML che possono essere usati per questo esempio sono presenti dopo l'esempio (xmltest.xml e xmltest2.xml.)

Esempio 3. Esempio di entità esterna
<?php $file = "xmltest.xml"; function trustedFile($file) { // si considera affidabili soltanto i file locali del proprio utente if (!eregi("^([a-z]+)://", $file) && fileowner($file) == getmyuid()) { return true; } return false; } function startElement($parser, $name, $attribs) { echo "<<font color=\"#0000cc\">$name</font>"; if (sizeof($attribs)) { while (list($k, $v) = each($attribs)) { echo " <font color=\"#009900\">$k</font>=\"<font color=\"#990000\">$v</font>\""; } } echo ">"; } function endElement($parser, $name) { echo "</<font color=\"#0000cc\">$name</font>>"; } function characterData($parser, $data) { echo "<b>$data</b>"; } function PIHandler($parser, $target, $data) { switch (strtolower($target)) { case "php": global $parser_file; // Se il documento analizzato è "affidabile", si può dire che è sicura // l'esecuzione del codice PHP presente in esso. In caso contrario si visualizza // il codice. if (trustedFile($parser_file[$parser])) { eval($data); } else { printf("Codice PHP inaffidabile: <i>%s</i>", htmlspecialchars($data)); } break; } } function defaultHandler($parser, $data) { if (substr($data, 0, 1) == "&" && substr($data, -1, 1) == ";") { printf('<font color="#aa00aa">%s</font>', htmlspecialchars($data)); } else { printf('<font size="-1">%s</font>', htmlspecialchars($data)); } } function externalEntityRefHandler($parser, $openEntityNames, $base, $systemId, $publicId) { if ($systemId) { if (!list($parser, $fp) = new_xml_parser($systemId)) { printf("Non si riesce ad aprire l'entità %s at %s\n", $openEntityNames, $systemId); return false; } while ($data = fread($fp, 4096)) { if (!xml_parse($parser, $data, feof($fp))) { printf("XML error: %s at line %d while parsing entity %s\n", xml_error_string(xml_get_error_code($parser)), xml_get_current_line_number($parser), $openEntityNames); xml_parser_free($parser); return false; } } xml_parser_free($parser); return true; } return false; } function new_xml_parser($file) { global $parser_file; $xml_parser = xml_parser_create(); xml_parser_set_option($xml_parser, XML_OPTION_CASE_FOLDING, 1); xml_set_element_handler($xml_parser, "startElement", "endElement"); xml_set_character_data_handler($xml_parser, "characterData"); xml_set_processing_instruction_handler($xml_parser, "PIHandler"); xml_set_default_handler($xml_parser, "defaultHandler"); xml_set_external_entity_ref_handler($xml_parser, "externalEntityRefHandler"); if (!($fp = @fopen($file, "r"))) { return false; } if (!is_array($parser_file)) { settype($parser_file, "array"); } $parser_file[$xml_parser] = $file; return array($xml_parser, $fp); } if (!(list($xml_parser, $fp) = new_xml_parser($file))) { die("Non si riesce ad aprire il documento XML"); } echo "<pre>"; while ($data = fread($fp, 4096)) { if (!xml_parse($xml_parser, $data, feof($fp))) { die(sprintf("Errore XML: %s alla linea %d\n", xml_error_string(xml_get_error_code($xml_parser)), xml_get_current_line_number($xml_parser))); } } echo "</pre>"; echo "parsing completato\n"; xml_parser_free($xml_parser); ?>

Esempio 4. xmltest.xml
<?xml version='1.0'?> <!DOCTYPE chapter SYSTEM "/just/a/test.dtd" [ <!ENTITY plainEntity "FOO entity"> <!ENTITY systemEntity SYSTEM "xmltest2.xml"> ]> <chapter> <TITLE>Title &plainEntity;</TITLE> <para> <informaltable> <tgroup cols="3"> <tbody> <row><entry>a1</entry><entry morerows="1">b1</entry><entry>c1</entry></row> <row><entry>a2</entry><entry>c2</entry></row> <row><entry>a3</entry><entry>b3</entry><entry>c3</entry></row> </tbody> </tgroup> </informaltable> </para> &systemEntity; <section id="about"> <title>Circa questo documento</title> <para>  <?php echo 'Ciao! Questa è la versione di PHP '.phpversion(); ?> </para> </section> </chapter>

Questo file è stato richiamato da xmltest.xml:
Esempio 5. xmltest2.xml
<?xml version="1.0"?> <!DOCTYPE foo [ <!ENTITY testEnt "Entità di test"> ]> <foo> <element attrib="value"/> &testEnt; <?php echo "Questa è una ulteriore riga di codice PHP eseguito."; ?> </foo>

Sommario
utf8_decode -- Converte una stringa con caratteri ISO-8859-1 codificati con UTF-8 in formato ISO-8859-1 singolo byte
utf8_encode -- Codifica una stringa da ISO-8859-1 a UTF-8
xml_error_string -- Restituisce la stringa di errore dal parser XML
xml_get_current_byte_index -- Restituisce il corrente indice di posizione per un parser XML
xml_get_current_column_number -- Restituisce il numero di colonna corrente di un parser XML
xml_get_current_line_number -- Restituisce il numero di linea corrente da un parser XML
xml_get_error_code -- Restituisce il codice di errore dal parser XML
xml_parse_into_struct -- Analisi di dati XML in una struttura a matrice
xml_parse -- Inizia il parsing di un documento XML
xml_parser_create_ns -- Crea un parser XML con il supporto dello spazio dei nomi
xml_parser_create -- Crea un parser XML
xml_parser_free -- Cancella un parser XML
xml_parser_get_option -- Restituisce le opzioni da un parser XML
xml_parser_set_option -- Valorizza un'opzione di un parser XML
xml_set_character_data_handler -- Valorizza il gestore dei dati
xml_set_default_handler -- Valorizza il gestore di default
xml_set_element_handler -- Valorizza i gestori di inizio e fine elemento
xml_set_end_namespace_decl_handler -- Valorizza il gestore dello spazio dei nomi
xml_set_external_entity_ref_handler -- Valorizza il gestore dei riferimenti a entità esterne
xml_set_notation_decl_handler -- Valorizza il gestore delle dichiarazione delle notazioni
xml_set_object -- Utilizza il parser XML all'interno di un oggetto
xml_set_processing_instruction_handler -- Indica il gestore delle istruzioni di processo (PI)
xml_set_start_namespace_decl_handler -- Valorizza il gestore dei caratteri di dati
xml_set_unparsed_entity_decl_handler -- Valorizza il gestore delle dichiarazioni di entità non analizzate

utf8_decode

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

utf8_decode -- Converte una stringa con caratteri ISO-8859-1 codificati con UTF-8 in formato ISO-8859-1 singolo byte

Descrizione

string utf8_decode ( string data )

Questa funzione decodifica il parametro data, considerato codificato in UTF-8, alla codifica ISO-8859-1.

Vedere anche utf8_encode() per dettagli sulla codifica UTF-8.

utf8_encode

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

utf8_encode -- Codifica una stringa da ISO-8859-1 a UTF-8

Descrizione

string utf8_encode ( string data )

Questa funzione converte la stringa data al formato UTF-8, e restituisce la nuova versione. UTF-8 è il meccanismo standard utilizzato da Unicode per la codifica dei valori wide character in un flusso di byte. La codifica UTF-8 è trasparente ai caratteri ASCII, è auto-sincronizzata (per un programma è possibile determinare dove iniziano i caratteri in un flusso di dati) e può essere usata nelle normali funzioni di confronto di stringhe per i sort e simili. Il PHP codifica i caratteri UTF-8 fino a quattro byte come segue:

Tabella 1. Codifica UTF-8

bytes	bits	rappresentazione
1	7	0bbbbbbb
2	11	110bbbbb 10bbbbbb
3	16	1110bbbb 10bbbbbb 10bbbbbb
4	21	11110bbb 10bbbbbb 10bbbbbb 10bbbbbb

Ciascuna b rappresenta un bit che può essere utilizzato per registrare le informazioni del carattere.

xml_error_string

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

xml_error_string -- Restituisce la stringa di errore dal parser XML

Descrizione

string xml_error_string ( int codice_errore )

codice_errore: Un codice di errore da xml_get_error_code().

La funzione restituisce una stringa con la descrizione dell'errore codice_errore, oppure FALSE se non si trova una descrizione.

xml_get_current_byte_index

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

xml_get_current_byte_index -- Restituisce il corrente indice di posizione per un parser XML

Descrizione

int xml_get_current_byte_index ( resource parser )

parser: Il riferimento al parser XML da cui si vuole ottenere la posizione.

Questa funzione restituisce FALSE se parser non si riferisce ad un parser valido, altrimenti la funzione restituisce in quale byte si trova attualmente il parser nel buffer dei dati (partendo da 0).

xml_get_current_column_number

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

xml_get_current_column_number -- Restituisce il numero di colonna corrente di un parser XML

Descrizione

int xml_get_current_column_number ( resource parser )

parser: Il riferimento al parser XML da cui ottenere il numero di colonna.

Questa funzione restituisce FALSE se parser non si riferisce ad un parser valido, altrimenti restituisce in quale colonna sulla linea corrente (come indicato da xml_get_current_line_number()) si trova il parser.

xml_get_current_line_number

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

xml_get_current_line_number -- Restituisce il numero di linea corrente da un parser XML

Descrizione

int xml_get_current_line_number ( resource parser )

parser: Il riferimento al parser XML da cui si vuole ottenere il numero di linea.

Questa funzione restituisce FALSE se parser non si riferisce ad un parser valido, altrimenti la funzione restituisce in quale linea del buffer dati si trova attualmente il parser.

xml_get_error_code

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

xml_get_error_code -- Restituisce il codice di errore dal parser XML

Descrizione

int xml_get_error_code ( resource parser )

parser: Il riferimento al parser XML da cui si vuole ottenere il codice di errore.

Questa funzione restituisce FALSE se parser non si riferisce ad un parser valido, altrimenti la funzione restituisce uno dei codici di errore elencati in codici di errore.

Vedere anche xml_error_string().

xml_parse_into_struct

(PHP 3 >= 3.0.8, PHP 4, PHP 5)

xml_parse_into_struct -- Analisi di dati XML in una struttura a matrice

Descrizione

int xml_parse_into_struct ( resource parser, string data, array &valori [, array &indice] )

Questa funzione registra un file XML in 2 strutture a matrice, una (indice) contiene i puntatori alla posizione dei valori nella matrice valori. Questi due parametri devono essere passati per riferimento.

Nota: La funzione xml_parse_into_struct() restituisce 0 in caso di errore e 1 in caso di successo. Questo non è lo stesso di FALSE e TRUE, fare attenzione con gli operatori tipo ===.

Nell'esempio seguente si illustra la struttura interna delle matrici generata dalla funzione. Qui si userà una semplice struttura con il tag note inserito all'interno del tag para, e quindi si analizzerà questo visualizzando la struttura ottenuta:
Esempio 1. Esempio di uso di xml_parse_into_struct()
<?php $simple = "<para><note>simple note</note></para>"; $p = xml_parser_create(); xml_parse_into_struct($p, $simple, $vals, $index); xml_parser_free($p); echo "Array indice\n"; print_r($index); echo "\narray dei valori\n"; print_r($vals); ?>
Eseguendo questo codice si otterrà:
Array indice Array ( [PARA] => Array ( [0] => 0 [1] => 2 ) [NOTE] => Array ( [0] => 1 ) ) Array dei valori Array ( [0] => Array ( [tag] => PARA [type] => open [level] => 1 ) [1] => Array ( [tag] => NOTE [type] => complete [level] => 2 [value] => simple note ) [2] => Array ( [tag] => PARA [type] => close [level] => 1 ) )

Un parsing event-driven (basato sulla libreria expat) può essere molto complicato se si deve trattare un documento XML complesso. Questa funzione non produce un oggetto in stile DOM, ma genera una struttura che permette di essere gestita a modo di albero. Quindi si può facilmente creare oggetti rappresentanti i dati del file XML. Si consideri il seguente file XML rappresentante un piccolo database di informazioni sugli aminoacidi.
Esempio 2. moldb.xml - piccolo database di informazioni sulle molecole
<?xml version="1.0"?> <moldb> <molecule> <name>Alanine</name> <symbol>ala</symbol> <code>A</code> <type>hydrophobic</type> </molecule> <molecule> <name>Lysine</name> <symbol>lys</symbol> <code>K</code> <type>charged</type> </molecule> </moldb>
Un codice per analizzare il documento e generare gli oggetti appropriati:
Esempio 3. parsemoldb.php - analizza moldb.xml e genera una matrice di oggetti molecole
<?php class AminoAcid { var $name; // aa nome var $symbol; // simbolo di tre lettere var $code; // codice di una lettera var $type; // hydrophobic, charged or neutral function AminoAcid ($aa) { foreach ($aa as $k=>$v) $this->$k = $aa[$k]; } } function readDatabase($filename) { // legge il database degli aminoacidi $data = implode("", file($filename)); $parser = xml_parser_create(); xml_parser_set_option($parser, XML_OPTION_CASE_FOLDING, 0); xml_parser_set_option($parser, XML_OPTION_SKIP_WHITE, 1); xml_parse_into_struct($parser, $data, $values, $tags); xml_parser_free($parser); // loop attraverso la struttura foreach ($tags as $key=>$val) { if ($key == "molecule") { $molranges = $val; // ciascuna coppia di elementi della matrice contigui // sono il limite inferiore e superiore per la definizione di ciascuna molecola for ($i=0; $i < count($molranges); $i+=2) { $offset = $molranges[$i] + 1; $len = $molranges[$i + 1] - $offset; $tdb[] = parseMol(array_slice($values, $offset, $len)); } } else { continue; } } return $tdb; } function parseMol($mvalues) { for ($i=0; $i < count($mvalues); $i++) $mol[$mvalues[$i]["tag"]] = $mvalues[$i]["value"]; } return new AminoAcid($mol); } $db = readDatabase("moldb.xml"); echo "** Database di oggetti Aminoacidi:\n"; print_r($db); ?>
Dopo l'esecuzione di parsemoldb.php, la variabile $db contiene una matrice di oggetti AminoAcid, e ciò viene confermato dall'output dello script:

** Database di oggetti Aminoacidi:
Array
(
    [0] => aminoacid Object
        (
            [name] => Alanine
            [symbol] => ala
            [code] => A
            [type] => hydrophobic
        )

    [1] => aminoacid Object
        (
            [name] => Lysine
            [symbol] => lys
            [code] => K
            [type] => charged
        )

)

xml_parse

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

xml_parse -- Inizia il parsing di un documento XML

Descrizione

bool xml_parse ( resource parser, string data [, bool e_finale] )

La funzione xml_parse() esegue il parsing di un documento XML. Gli handler configurati per la gestione degli eventi saranno richiamati ogni volta che si renderà necessario.

Elenco dei parametri

parser: Il riferimento al parser XML da utilizzare.
data: Segmento di dati da analizzare. Un documento può essere elaborato a segmenti richiamando xml_parse() diverse volte con nuovi dati, con il parametro e_finale settato a TRUE quando si elabora l'ultimo segmento.
e_finale (optional): Se valorizzato a TRUE, il parametro data rappresenta l'ultimo segmento dei dati inviati al parser.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

In caso di parsing non riuscito, si può recuperare informazioni sull'errore usando xml_get_error_code(), xml_error_string(), xml_get_current_line_number(), xml_get_current_column_number() e xml_get_current_byte_index().

Nota: Gli errori nelle entità sono riportati alla fine dei dati questo soltanto se is_final è impostato a TRUE.

xml_parser_create_ns

(PHP 4 >= 4.0.5, PHP 5)

xml_parser_create_ns -- Crea un parser XML con il supporto dello spazio dei nomi

Descrizione

resource xml_parser_create_ns ( [string codifica [, string separatore]] )

La funzione xml_parser_create_ns() crea un nuovo parser XML con il supporto dello spazio dei nomi XML e restituisce un handle da utilizzarsi con le altre funzioni XML.

mixed xml_parser_get_option ( resource parser, int opzione )

parser: Riferimento al parser XML da cui ottenere l'opzione
opzione: Quale opzione ottenere. Vedere xml_parser_set_option() per l'elenco delle opzioni.

Questa funzione restituisce FALSE se parser non si riferisce ad un parser valido, o se option non è valido (viene anche generato un E_WARNING). Altrimenti viene restituito il valore dell'opzione.

Vedere xml_parser_set_option() per l'elenco delle opzioni.

xml_parser_set_option

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

xml_parser_set_option -- Valorizza un'opzione di un parser XML

Descrizione

bool xml_parser_set_option ( resource parser, int opzione, mixed valore )

parser: Riferimento al parser XML di cui si vuole valorizzare l'opzione,
opzione: Quale opzione valorizzare. Vedere più avanti.
valore: Nuovo valore dell'opzione.

Questa funzione restituisce FALSE se parser non si riferisce ad un parser valido, o se l'opzione non può essere valorizzata. Altrimenti l'opzione viene valorizzata e la funzione restituisce TRUE.

Sono disponibili le seguenti opzioni:

Tabella 1. Opzioni del parser XML

Costante dell'opzione	tipo di dato	Descrizione
XML_OPTION_CASE_FOLDING	integer	Controlla se il case-folding è abilitato per questo parser XML. Abilitato per default.
XML_OPTION_SKIP_TAGSTART	integer	Indica quanti caratteri devono essere ignorati dall'inizio del nome del tag.
XML_OPTION_SKIP_WHITE	integer	Indica se contare anche gli spazi nei caratteri da ignorare.
XML_OPTION_TARGET_ENCODING	string	Indica quale target encoding utilizzare in questo parser XML. Per default, è valorizzato con la medesima codifica del sorgente utilizzata da xml_parser_create(). Le codifiche supportate per il destinatario sono `ISO-8859-1`, `US-ASCII` e `UTF-8`.

xml_set_character_data_handler

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

xml_set_character_data_handler -- Valorizza il gestore dei dati

Descrizione

bool xml_set_character_data_handler ( resource parser, callback gestore )

Valorizza la funzione di gestione dei dati per il parser XML parser. Il parametro gestore è una stringa contenente il nome di una funzione che deve esistere quando viene richiamata la funzione xml_parse() per il parser.

La fuzione indicata in gestore deve accettare due parametri: gestore ( resource parser, string dati )

parser: Il primo parametro, parser, è un riferimento al parser XML chiamante il gestore.
dati: Il secondo parametro, dati, è una stringa contenente i dati.

Se il nome della funzione di gestione viene indicato come una stringa vuota o FALSE il gestore in questione viene disabilitato.

La funzione restituisce TRUE se il gestore viene valorizzato, oppure FALSE se parser non indica un parser.

Nota: Invece di un nome di funzione è possibile passare un vettore contenente un riferimento ad un oggetto e un nome di metodo.

xml_set_default_handler

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

xml_set_default_handler -- Valorizza il gestore di default

Descrizione

bool xml_set_default_handler ( resource parser, callback gestore )

Questa funzione valorizza il gestore di default per parser. Il parametro gestore è una stringa contenente il nome di una funzione che deve esistere quando viene eseguito xml_parse() per il parser XML.

La funzione indicata da gestore deve accettare due parametri: gestore ( resource parser, string dati )

parser: Il primo parametro, parser, è un riferimento al parser XML chiamante il gestore.
dati: Il secondo parametro, dati, contiene i dati. Questi possono essere dichiarazioni XML, dichiarazioni di tipo documento, entità oppure altri dati per i quali non è definito il gestore.

Se il nome della funzione del gestore viene valorizzato con una stringa vuota oppure a FALSE, il gestore in questione viene disabilitato.

La funzione restituisce TRUE se il gestore viene attivato, FALSE se parser non indica un parser XML.

Nota: Invece di un nome di funzione è possibile passare un vettore contenente un riferimento ad un oggetto e un nome di metodo.

xml_set_element_handler

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

xml_set_element_handler -- Valorizza i gestori di inizio e fine elemento

Descrizione

bool xml_set_element_handler ( resource parser, callback gestore_inizio_elemento, callback gestore_fine_elemento )

La funzione indica le funzioni di gestione di inizio e fine elemento per il parser XML. gestore_inizio_elemento e gestore_fine_elemento sono stringhe contenenti i nomi di funzioni che devono esistere quando viene eseguito xml_parse() per il parser.

La funzione indicata da gestore_inizio_elemento deve accettare tre parametri: gestore ( resource parser, string nome, array attibuti )

parser

Il primo parametro, parser, è il riferimento al parser XML chiamante il gestore.

nome

Il secondo parametro, nome, contiene il nome dell'elemento per il quale viene chiamato il gestore. Se è attivo il case-folding per questo parser, il nome dell'elemento sarà in maiuscolo.

attributi

Il terzo parametro, attributi, contiene un array associativo con gli attributi dell'elemento (se presenti). Le chiavi di questo array sono i nomi degli attributi, mentre i valori delle chiavi sono i valori degli attributi. I nomi degli attributi sono case-folded allo stesso modo dei nomi degli elementi. I valori degli attributi non lo sono.

L'ordine originale degli attributi può essere recuperato attraversando attributi in modo normale utilizzando la funzione each(). La prima chiave dell'array è il primo attributo, e così via.

La funzione indicata da gestore_fine_elemento deve accettare due parametri: gestore ( resource parser, string nome )

parser: Il primo parametro, parser, è il riferimento al parser XML chiamante il gestore.
nome: Il secondo parametro, nome, contiene il nome dell'elemento per il quale viene chiamato il gestore. Se è attivo il case-folding per questo parser, il nome dell'elemento sarà in maiuscolo.

Se il nome della funzione del gestore viene valorizzato con una stringa vuota oppure a FALSE, il gestore in questione viene disabilitato.

La funzione restituisce TRUE se il gestore viene attivato, FALSE se parser non indica un parser XML.

Nota: Invece di un nome di funzione è possibile passare un vettore contenente un riferimento ad un oggetto e un nome di metodo.

xml_set_end_namespace_decl_handler

(PHP 4 >= 4.0.5, PHP 5)

xml_set_end_namespace_decl_handler -- Valorizza il gestore dello spazio dei nomi

Descrizione

bool xml_set_end_namespace_decl_handler ( resource parser, callbaccallback hdl )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Nota: Invece di un nome di funzione è possibile passare un vettore contenente un riferimento ad un oggetto e un nome di metodo.

xml_set_external_entity_ref_handler

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

xml_set_external_entity_ref_handler -- Valorizza il gestore dei riferimenti a entità esterne

Descrizione

bool xml_set_external_entity_ref_handler ( resource parser, callback gestore )

Indica al parser XML parser la funzione per la gestione dei riferimenti a entità esterne. Il gestore è una stringa contenente il nome di una funzione che deve esistere quando viene eseguita la funzione xml_parse() per il parser.

La funzione indicata da gestore deve accettare cinque parametri, e dovrebbe restituire un intero. Se il valore restituito dal gestore è FALSE (valore assunto per default in caso di nessun valore restituito), il parser XML ferma l'elaborazione e xml_get_error_code() restituirà XML_ERROR_EXTERNAL_ENTITY_HANDLING. gestore ( resource parser, string nomi_entita_aperte, string base, string system_id, string public_id )

parser: Il primo parametro, parser, è il riferimento al parser XML chiamante il gestore.
nome_entita_aperte: Il secondo parametro, nomi_entita_aperte, è una lista di nomi, separati da spazio, delle entità che saranno aperte per il parsing di questa entità (compreso il nome dell'entità indicata)
base: Questa è la base per la risoluzione dell'identificatore system (systemid) delle entità esterne. Attualmente questo parametro è sempre valorizzato con una stringa vuota.
system_id: Il quarto parametro, system_id, è l'identificatore system come specificato nella dichiarazione dell'entità.
public_id: Il quinto parametro, public_id, è l'identificatore public come specificato nella dichiarazione dell'entità, oppure una stringa vuota se non viene specificato; lo spazio nell'identificatore public è normalizzato come richiesto dalle specifiche XML.

Se il nome della funzione del gestore viene valorizzato con una stringa vuota oppure a FALSE, il gestore in questione viene disabilitato.

La funzione restituisce TRUE se il gestore viene attivato, FALSE se parser non indica un parser XML.

Nota: Invece di un nome di funzione è possibile passare un vettore contenente un riferimento ad un oggetto e un nome di metodo.

xml_set_notation_decl_handler

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

xml_set_notation_decl_handler -- Valorizza il gestore delle dichiarazione delle notazioni

Descrizione

bool xml_set_notation_decl_handler ( resource parser, callback handler )

Indica al parser XML parser la funzione per la gestione delle dichiarazioni delle notazioni. Il gestore è una stringa contenente il nome di una funzione che deve esistere quando viene eseguita la funzione xml_parse() per il parser.

La dichiarazione di una notazione è una parte della DTD del documento ed ha il seguente formato:
<!NOTATION <parameter>name</parameter> { <parameter>system_id</parameter> | <parameter>public_id</parameter>?>
Vedere la sezione 4.7 delle specifiche XML 1.0 per la definizione delle dichiarazioni delle notazioni.

La funzione indicata da gestore deve accettare cinque parametri: gestore ( resource parser, string nome_notazione, string base, string system_id, string public_id )

parser: Il primo parametro, parser, è il riferimento al parser XML chiamante il gestore.
nome_notazione: Questo è il parametro name della notazione, come dal formato descritto in precedenza.
base: Questa è la base per la risoluzione dell'identificatore system (system_id) delle entità esterne. Attualmente questo parametro è sempre valorizzato con una stringa vuota.
system_id: Identificatore system della dichiarazione della notazione esterna.
public_id: Identificatore public della dichiarazione della notazione esterna.

Se il nome della funzione del gestore viene valorizzato con una stringa vuota oppure a FALSE, il gestore in questione viene disabilitato.

La funzione restituisce TRUE se il gestore viene attivato, FALSE se parser non indica un parser XML.

Nota: Invece di un nome di funzione è possibile passare un vettore contenente un riferimento ad un oggetto e un nome di metodo.

xml_set_object

(PHP 4, PHP 5)

xml_set_object -- Utilizza il parser XML all'interno di un oggetto

Descrizione

void xml_set_object ( resource parser, object &oggetto )

Questa funzione permette l'uso del parser all'interno di un oggetto. Tutte le funzioni di callback possono essere indicate con xml_set_element_handler() e simili, e sono assunte come metodi dell'oggetto.

Esempio 1. Esempio di uso di xml_set_object()
<?php class xml { var $parser; function xml() { $this->parser = xml_parser_create(); xml_set_object($this->parser, $this); xml_set_element_handler($this->parser, "tag_open", "tag_close"); xml_set_character_data_handler($this->parser, "cdata"); } function parse($data) { xml_parse($this->parser, $data); } function tag_open($parser, $tag, $attributes) { var_dump($parser, $tag, $attributes); } function cdata($parser, $cdata) { var_dump($parser, $cdata); } function tag_close($parser, $tag) { var_dump($parser, $tag); } } // fine della classe xml $xml_parser = new xml(); $xml_parser->parse("<A ID='hallo'>PHP</A>"); ?>

xml_set_processing_instruction_handler

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

xml_set_processing_instruction_handler -- Indica il gestore delle istruzioni di processo (PI)

Descrizione

bool xml_set_processing_instruction_handler ( resource parser, callback gestore )

Indica al parser XML parser la funzione per la gestione delle istruzioni di processo (PI). Il gestore è una stringa contenente il nome di una funzione che deve esistere quando viene eseguita la funzione xml_parse() per il parser.

Le istruzioni di processo hanno il seguente formato:

<?
       target 
       data?>

Si può inserire codice PHP all'interno di questo tipo di tag, ma occorre fare attenzione ad una limitazione: in una PI XML, il tag di fine PI (?>) non può essere tra apici, pertanto questa seguenza di caratteri non dovrebbe apparire nel codice PHP che si inserisce nel documento XML con le PIs. Se ciò accade il resto del codice PHP, come il "reale" tag di fine PI, saranno trattati come caratteri di dati.

La funzione indicata da gestore deve accettare tre parametri: gestore ( resource parser, string target, string dati )

parser: Il primo parametro, parser, è il riferimento al parser XML chiamante il gestore.
target: Il secondo parametro, target, contiene la PI target.
dati: Il terzo parametro, dati, contiene i dati del PI.

Se il nome della funzione del gestore viene valorizzato con una stringa vuota oppure a FALSE, il gestore in questione viene disabilitato.

La funzione restituisce TRUE se il gestore viene attivato, FALSE se parser non indica un parser XML.

Nota: Invece di un nome di funzione è possibile passare un vettore contenente un riferimento ad un oggetto e un nome di metodo.

xml_set_start_namespace_decl_handler

(PHP 4 >= 4.0.5, PHP 5)

xml_set_start_namespace_decl_handler -- Valorizza il gestore dei caratteri di dati

Descrizione

bool xml_set_start_namespace_decl_handler ( resource parser, callback handler )

Avvertimento

Questa funzione, al momento non è documentata; è disponibile soltanto la lista degli argomenti.

Nota: Invece di un nome di funzione è possibile passare un vettore contenente un riferimento ad un oggetto e un nome di metodo.

xml_set_unparsed_entity_decl_handler

(PHP 3 >= 3.0.6, PHP 4, PHP 5)

xml_set_unparsed_entity_decl_handler -- Valorizza il gestore delle dichiarazioni di entità non analizzate

Descrizione

bool xml_set_unparsed_entity_decl_handler ( resource parser, callback gestore )

Indica al parser XML parser la funzione per la gestione delle dichiarazioni di entità non analizzate. Il gestore è una stringa contenente il nome di una funzione che deve esistere quando viene eseguita la funzione xml_parse() per il parser.

Questo gestore viene richiamato quando il parser XML incontra una dichiarazione di entità esterna con una dichiarazione NDATA, tipo la seguente:
<!ENTITY <parameter>name</parameter> {<parameter>publicId</parameter> | <parameter>systemId</parameter>} NDATA <parameter>notationName</parameter>

Vedere la sezione 4.2.2 delle specifiche di XML 1.0 per la definizione di notazioni dichiarate in entità esterne.

La funzione indicata da gestore deve accettare sei parametri: gestore ( resource parser, string nome_entità, string base, string system_id, string public_id, string nome_notazione )

parser: Il primo parametro, parser, è il riferimento al parser XML chiamante il gestore.
nome_entità: Il nome dell'entità che sta per essere definita.
base: Questa è la base per la risoluzione dell'identificatore system (systemid) delle entità esterne. Attualmente questo parametro è sempre valorizzato con una stringa vuota.
system_id: Identificatore system per l'entità esterna.
public_id: Identificatore public per l'entità esterna.
nome_notazione: Nome della notazione di questa entità (vedere xml_set_notation_decl_handler()).

Se il nome della funzione del gestore viene valorizzato con una stringa vuota oppure a FALSE, il gestore in questione viene disabilitato.

La funzione restituisce TRUE se il gestore viene attivato, FALSE se parser non indica un parser XML.

Nota: Invece di un nome di funzione è possibile passare un vettore contenente un riferimento ad un oggetto e un nome di metodo.

CLXII. Funzioni XML-RPC

Introduzione

Queste funzioni possono essere utilizzate per scrivere client e server XML-RPC. Si possono trovare maggiori informazioni sul XML-RPC in http://www.xmlrpc.com/, e maggiore documentazione su questo modulo e le sue funzioni in http://xmlrpc-epi.sourceforge.net/.

Avvertimento

Requisiti

Non sono necessarie librerie esterne per utilizzare questo modulo.

Installazione

Per default il modulo XML-RPC non è abilitato in PHP. Per abilitarlo occorre utilizzare il perametro di configurazione --with-xmlrpc[=DIR] in fase di compila del PHP. Questo modulo è rilasciato con il PHP dalla versione 4.1.0.

Configurazione di Runtime

Il comportamento di queste funzioni è influenzato dalle impostazioni di php.ini.

Tabella 1. Parametri di configurazione XML-RPC

Nome	Default	Modificabile	Variazioni
xmlrpc_errors	"0"	PHP_INI_SYSTEM	Disponibile dal PHP 4.1.0.
xmlrpc_error_number	"0"	PHP_INI_ALL	Disponibile dal PHP 4.1.0.

Per maggiori dettagli sulle costanti PHP_INI_* vedere Appendice G.

Tipi di risorse

Questa estensione non definisce alcun tipo di risorsa.

Costanti predefinite

Questa estensione non definisce alcuna costante.

Sommario
xmlrpc_decode_request -- Decodifica XML nei nativi tipi di PHP
xmlrpc_decode -- Decodifica XML nei nativi tipi di PHP
xmlrpc_encode_request -- Genera XML per un metodo di richiesta
xmlrpc_encode -- Genera XML per un valore PHP
xmlrpc_get_type -- Riceve il tipo di xmlrpc per un valore PHP. Maggiormente ì usato per le stringhe base64 e datetime
xmlrpc_is_fault -- Determines if an array value represents an XMLRPC fault
xmlrpc_parse_method_descriptions -- Decodifica XML in una lista di method descriptions
xmlrpc_server_add_introspection_data -- Aggiunge documentazione introspettiva
xmlrpc_server_call_method -- Struttura le richieste XML e i metodi di chiamata
xmlrpc_server_create -- Crea un server xmlrpc
xmlrpc_server_destroy -- Distrugge le risorse del server
xmlrpc_server_register_introspection_callback -- Registra una funzione PHP per generare la documentazione
xmlrpc_server_register_method -- Registra una funzione PHP nel metodo di risorsa abbinato method_name
xmlrpc_set_type -- Imposta il tipo di xmlrpc, base64 o datetime, per un valore di stringa PHP

CLXIII. XMLReader functions

Introduzione

The XMLReader extension is an XML Pull parser. The reader acts as a cursor going forward on the document stream and stopping at each node on the way.

Installazione

The XMLReader extension is available in PECL for PHP 5.0 and is included in PHP 5.1 by default. It and can be enabled by adding the argument --with--xmlreader to your configure line. The libxml extension is required.

Classi predefinite

XMLReader

Metodi

XMLReader->close() - Close the XMLReader input
XMLReader->expand() - Export current node to a DOM node
XMLReader->getAttribute() - Get value of attribute by name
XMLReader->getAttributeNo() - Get value of attribute by position
XMLReader->getAttributeNS() - Get value of attribute by name and URI
XMLReader->getParserProperty() - Indicates if parser property is set or not
XMLReader->isValid() - Indicates if document is valid
XMLReader->lookupNamespace() - Get URI for prefix in scope of node
XMLReader->moveToAttribute() - Positions reader on named attribute
XMLReader->moveToAttributeNo() - Positions reader on attribute by index
XMLReader->moveToAttributeNs() - Position reader on attribute by name and URI
XMLReader->moveToElement() - Move to parent element of current attribute node
XMLReader->moveToFirstAttribute() - Move to first attribute of node
XMLReader->moveToNextAttribute() - Move to next attribute of node
XMLReader->next() - Move to next element skipping children
XMLReader->open() - Set URI to be parsed
XMLReader->read() - Move to next node in stream
XMLReader->setParserProperty() - Set parser property
XMLReader->setRelaxNGSchema() - Set URI of RelaxNG schema to validate against
XMLReader->setRelaxNGSchemaSource() - Set string containing RelaxNG schema to validate against
XMLReader->XML() - Set string of data to be parsed

Proprietà

Tabella 1.

Name	Type	Read-only	Description
attributeCount	int	yes	The number of attributes on the node
baseURI	string	yes	The base URI of the node
depth	int	yes	Depth of the node in the tree starting at 0
hasAttributes	bool	yes	Indicates if node has attributes
hasValue	bool	yes	Indicates if node has a text value
isDefault	bool	yes	Indicates if attribute is defaulted from DTD
isEmptyElement	bool	yes	Indicates if node is an empty element tag
localName	string	yes	The local name of the node
name	string	yes	The qualified name of the node
namespaceURI	string	yes	The URI of the namespace associated with the node
nodeType	int	yes	The node type for the node
prefix	string	yes	The prefix of the namespace associated with the node
value	string	yes	The text value of the node
xmlLang	string	yes	The xml:lang scope which the node resides

Costanti predefinite

Queste costanti sono definite da questa estensione e sono disponibili solo se l'estensione è stata compilata nel PHP o se è stata caricata dinamicamente a runtime.

Tabella 2. XMLReader Node Types

Constant	Value	Description
`XMLREADER_NONE` (integer)	0	No node type
`XMLREADER_ELEMENT` (integer)	1	Start element
`XMLREADER_ATTRIBUTE` (integer)	2	Attribute node
`XMLREADER_TEXT` (integer)	3	Text node
`XMLREADER_CDATA` (integer)	4	CDATA node
`XMLREADER_ENTITY_REF` (integer)	5	Entity Reference node
`XMLREADER_ENTITY` (integer)	6	Entity Declaration node
`XMLREADER_PI` (integer)	7	Processing Instruction node
`XMLREADER_COMMENT` (integer)	8	Comment node
`XMLREADER_DOC` (integer)	9	Document node
`XMLREADER_DOC_TYPE` (integer)	10	Document Type node
`XMLREADER_DOC_FRAGMENT` (integer)	11	Document Fragment node
`XMLREADER_NOTATION` (integer)	12	Notation node
`XMLREADER_WHITESPACE` (integer)	13	Whitespace node
`XMLREADER_SIGNIFICANT_WHITESPACE` (integer)	14	Significant Whitespace node
`XMLREADER_END_ELEMENT` (integer)	15	End Element
`XMLREADER_END_ENTITY` (integer)	16	End Entity
`XMLREADER_XML_DECLARATION` (integer)	17	XML Declaration node

Tabella 3. XMLReader Parser Options

Constant	Value	Description
`XMLREADER_LOADDTD` (integer)	1	Load DTD but do not validate
`XMLREADER_DEFAULTATTRS` (integer)	2	Load DTD and default attributes but do not validate
`XMLREADER_VALIDATE` (integer)	3	Load DTD and validate while parsing
`XMLREADER_SUBST_ENTITIES` (integer)	4	Subsitute entities and expand references

Sommario
XMLReader->close() -- Close the XMLReader input
XMLReader->expand() -- Returns a copy of the current node as a DOM object
XMLReader->getAttribute() -- Get the value of a named attribute
XMLReader->getAttributeNo() -- Get the value of an attribute by index
XMLReader->getAttributeNS() -- Get the value of an attribute by localname and URI
XMLReader->getParserProperty() -- Indicates if specified property has been set
XMLReader->isValid() -- Indicates if the parsed document is valid
XMLReader->lookupNamespace() -- Lookup namespace for a prefix
XMLReader->moveToAttribute() -- Move cursor to a named attribute
XMLReader->moveToAttributeNo() -- Move cursor to an attribute by index
XMLReader->moveToAttributeNs() -- Move cursor to a named attribute
XMLReader->moveToElement() -- Position cursor on the parent Element of current Attribute
XMLReader->moveToFirstAttribute() -- Position cursor on the first Attribute
XMLReader->moveToNextAttribute() -- Position cursor on the next Attribute
XMLReader->next() -- Move cursor to next node skipping all subtrees
XMLReader->open() -- Set the URI containing the XML to parse
XMLReader->read() -- Move to next node in document
XMLReader->setParserProperty() -- Set or Unset parser options
XMLReader->setRelaxNGSchema() -- Set the filename or URI for a RelaxNG Schema
XMLReader->setRelaxNGSchemaSource() -- Set the data containing a RelaxNG Schema
XMLReader->XML() -- Set the data containing the XML to parse

XMLReader->close()

(no version information, might be only in CVS)

XMLReader->close() -- Close the XMLReader input

Descrizione

class XMLReader {

bool close ( void )

}

Closes the input the XMLReader object is currently parsing.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

XMLReader->open()

XMLReader->XML()

XMLReader->expand()

(no version information, might be only in CVS)

XMLReader->expand() -- Returns a copy of the current node as a DOM object

Descrizione

class XMLReader {

DOMNode expand ( void )

}

This method copies the current node and returns the appropriate DOM object.

Valori restituiti

The resulting DOMNode or FALSE on error.

XMLReader->getAttribute()

(no version information, might be only in CVS)

XMLReader->getAttribute() -- Get the value of a named attribute

Descrizione

class XMLReader {

string getAttribute ( string name )

}

Returns the value of a named attribute or an empty string if attribute does not exist or not positioned on an element node.

Elenco dei parametri

name: The name of the attribute.

Valori restituiti

The value of the attribute, or an empty string if no attribute with the given name is found or not positioned of element.

Vedere anche:

XMLReader->getAttributeNS()

XMLReader->getAttributeNo()

(no version information, might be only in CVS)

XMLReader->getAttributeNo() -- Get the value of an attribute by index

Descrizione

class XMLReader {

string getAttributeNo ( int index )

}

Returns the value of an attribute based on its position or an empty string if attribute does not exist or not positioned on an element node.

Elenco dei parametri

index: The position of the attribute.

Valori restituiti

The value of the attribute, or an empty string if no attribute exists at index or not positioned of element.

Vedere anche:

XMLReader->getAttribute()

XMLReader->getAttributeNS()

(no version information, might be only in CVS)

XMLReader->getAttributeNS() -- Get the value of an attribute by localname and URI

Descrizione

class XMLReader {

string getAttributeNS ( string localName, string namespaceURI )

}

Returns the value of an attribute by name and namespace URI or an empty string if attribute does not exist or not positioned on an element node.

Elenco dei parametri

localName: The local name.
namespaceURI: The namespace URI.

Valori restituiti

The value of the attribute, or an empty string if no attribute with the given localName and namespaceURI is found or not positioned of element.

Vedere anche:

XMLReader->getAttribute()

XMLReader->getAttributeNo()

XMLReader->getParserProperty()

(no version information, might be only in CVS)

XMLReader->getParserProperty() -- Indicates if specified property has been set

Descrizione

class XMLReader {

bool getParserProperty ( int property )

}

Indicates if specified property has been set.

Elenco dei parametri

property: One of the parser option constants.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

XMLReader->setParserProperty()

XMLReader->isValid()

(no version information, might be only in CVS)

XMLReader->isValid() -- Indicates if the parsed document is valid

Descrizione

class XMLReader {

bool isValid ( void )

}

Returns a boolean indicating if the document being parsed is currently valid.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

XMLReader->setParserProperty()

XMLReader->setRelaxNGSchema()

XMLReader->setRelaxNGSchemaSource()

XMLReader->lookupNamespace()

(no version information, might be only in CVS)

XMLReader->lookupNamespace() -- Lookup namespace for a prefix

Descrizione

class XMLReader {

bool lookupNamespace ( string prefix )

}

Lookup in scope namespace for a given prefix.

Elenco dei parametri

prefix: String containing the prefix.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

XMLReader->moveToAttribute()

(no version information, might be only in CVS)

XMLReader->moveToAttribute() -- Move cursor to a named attribute

Descrizione

class XMLReader {

bool moveToAttribute ( string name )

}

Positions cursor on the named attribute.

Elenco dei parametri

name: The name of the attribute.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

XMLReader->moveToAttributeNo()

(no version information, might be only in CVS)

XMLReader->moveToAttributeNo() -- Move cursor to an attribute by index

Descrizione

class XMLReader {

bool moveToAttributeNo ( int index )

}

Positions cursor on attribute based on its position.

Elenco dei parametri

index: The position of the attribute.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

XMLReader->moveToAttributeNs()

(no version information, might be only in CVS)

XMLReader->moveToAttributeNs() -- Move cursor to a named attribute

Descrizione

class XMLReader {

bool moveToAttributeNs ( string localName, string namespaceURI )

}

Positions cursor on the named attribute in specified namespace.

Elenco dei parametri

localName: The local name.
namespaceURI: The namespace URI.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

XMLReader->moveToElement()

(no version information, might be only in CVS)

XMLReader->moveToElement() -- Position cursor on the parent Element of current Attribute

Descrizione

class XMLReader {

bool moveToElement ( void )

}

Moves cursor to the parent Element of current Attribute. Returns TRUE if sucessful and FALSE if it fails or not positioned on Attribute when this method is called.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

(no version information, might be only in CVS)

XMLReader->moveToFirstAttribute() -- Position cursor on the first Attribute

Descrizione

class XMLReader {

bool moveToFirstAttribute ( void )

}

Moves cursor to the first Attribute.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

XMLReader->moveToNextAttribute()

(no version information, might be only in CVS)

XMLReader->moveToNextAttribute() -- Position cursor on the next Attribute

Descrizione

class XMLReader {

bool moveToNextAttribute ( void )

}

Moves cursor to the next Attribute if positioned on an Attribute or moves to first attribute if positioned on an Element.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

XMLReader->next()

(no version information, might be only in CVS)

XMLReader->next() -- Move cursor to next node skipping all subtrees

Descrizione

class XMLReader {

bool next ( [string localname] )

}

Positions cursor on the next node skipping all subtrees.

Elenco dei parametri

localname: The name of the next node to move to.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

XMLReader->next()

XMLReader->open()

(no version information, might be only in CVS)

XMLReader->open() -- Set the URI containing the XML to parse

Descrizione

class XMLReader {

bool open ( string URI )

}

Set the URI containing the XML document to be parsed.

Elenco dei parametri

URI: URI pointing to the document.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche:

XMLReader->XML()

XMLReader->close()

XMLReader->read()

(no version information, might be only in CVS)

XMLReader->read() -- Move to next node in document

Descrizione

class XMLReader {

bool read ( void )

}

Moves cursor to the next node in the document.

Valori restituiti

Restituisce TRUE in caso di successo, FALSE in caso di fallimento.

Vedere anche: