mirror of
https://github.com/php/doc-it.git
synced 2026-03-24 07:32:12 +01:00
2d3dbd42a0
git-svn-id: https://svn.php.net/repository/phpdoc/it/trunk@351144 c90b9560-bf6c-de11-be94-00142212c4b1
452 lines
14 KiB
XML
452 lines
14 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!-- EN-Revision: 4526a0712f78a2b1c41976dbdb230ff5245893f8 Maintainer: pastore Status: ready -->
|
|
<!-- CREDITS: darvina -->
|
|
<refentry xml:id="function.assert" xmlns="http://docbook.org/ns/docbook">
|
|
<refnamediv>
|
|
<refname>assert</refname>
|
|
<refpurpose>Verifica se un'asserzione è &false;</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsect1 role="description">
|
|
&reftitle.description;
|
|
<para>PHP 5</para>
|
|
<methodsynopsis>
|
|
<type>bool</type><methodname>assert</methodname>
|
|
<methodparam><type>mixed</type><parameter>assertion</parameter></methodparam>
|
|
<methodparam choice="opt"><type>string</type><parameter>description</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>PHP 7</para>
|
|
<methodsynopsis>
|
|
<type>bool</type><methodname>assert</methodname>
|
|
<methodparam><type>mixed</type><parameter>assertion</parameter></methodparam>
|
|
<methodparam choice="opt"><type>Throwable</type><parameter>exception</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
<function>assert</function> verifica l'
|
|
<parameter>assertion</parameter> data e prende gli opportuni provvedimenti se
|
|
il suo risultato è &false;.
|
|
</para>
|
|
<refsect2>
|
|
<title>Asserzioni tradizionali (PHP 5 e 7)</title>
|
|
<para>
|
|
Se il parametro <parameter>assertion</parameter> è una stringa, verrà
|
|
valutata come codice PHP da <function>assert</function>.
|
|
I vantaggi di usare le stringhe con <parameter>assertion</parameter> sono
|
|
meno overhead nella verifica e la visualizzazione dei messaggi
|
|
che contengono <parameter>assertion</parameter> quando
|
|
questa fallisce. Ciò significa che se si passa una condizione booleana
|
|
come <parameter>assertion</parameter>, questa condizione non sarà mostrata come
|
|
parametro della funzione di asserzione che può essere definita con la
|
|
funzione <function>assert_options</function>, la condizione è convertita
|
|
in una stringa prima di chiamare la funzione handler, e il valore booleano &false;
|
|
viene convertito in una stringa vuota.
|
|
</para>
|
|
<para>
|
|
Le asserzioni dovrebbero essere utilizzate solo per il debug. Si possono
|
|
usare per controlli di coerenza che testano per condizioni che dovrebbero
|
|
essere sempre &true; e che, in caso contrario, indichino errori di programmazione,
|
|
oppure per verificare la presenza o meno di certe caratteristiche, tipo le estensioni,
|
|
oppure certi limiti di sistema o caratteristiche.
|
|
</para>
|
|
<para>
|
|
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 debba funzionare correttamente anche disabilitando le regole di
|
|
asserzione.
|
|
</para>
|
|
<para>
|
|
Il comportamento di <function>assert</function> può essere impostato
|
|
tramite <function>assert_options</function> oppure tramite .ini-settings come descritto
|
|
nelle pagine del manuale relative a quelle funzioni.
|
|
</para>
|
|
<para>
|
|
La funzione <function>assert_options</function> e/o il parametro
|
|
<constant>ASSERT_CALLBACK</constant> permettono/e
|
|
di attivare una funzione di callback per gestire una asserzione fallita.
|
|
</para>
|
|
<para>
|
|
Le callback di <function>assert</function> 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
|
|
molto più veloce e semplice!
|
|
</para>
|
|
<para>
|
|
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 parametro conterrà l'espressione dell'asserzione fallita (se
|
|
qualsiasi — valore letterale come 1 o "due" non verrà passato con
|
|
questo parametro). Gli utenti di PHP 5.4.8 e successivi possono anche fornire un quarto
|
|
parametro opzionale, che conterrà la
|
|
<parameter>description</parameter> data all'<function>assert</function>, se
|
|
è stata impostata.
|
|
</para>
|
|
</refsect2>
|
|
<refsect2 xml:id="function.assert.expectations">
|
|
<title>Aspettative (solo PHP 7)</title>
|
|
<para>
|
|
<function>assert</function> è un costrutto del linguaggio in PHP 7, consentendo
|
|
la definizione delle aspettative: asserzioni che hanno effetto in ambienti di
|
|
sviluppo e di test, ma sono ottimizzate per avere un costo zero in
|
|
produzione.
|
|
</para>
|
|
<para>
|
|
Mentre <function>assert_options</function> può ancora essere utilizzata per controllare
|
|
il comportamento come sopra descritto per ragioni di retrocompatibilità, il codice
|
|
solo per PHP 7 dovrebbe usare le due nuove direttive di configurazione per controllare
|
|
il comportamento di <function>assert</function> e non chiamare
|
|
<function>assert_options</function>.
|
|
</para>
|
|
<table>
|
|
<title>
|
|
Direttive di configurazione di PHP 7 per <function>assert</function>
|
|
</title>
|
|
<tgroup cols="3">
|
|
<thead>
|
|
<row>
|
|
<entry>Direttiva</entry>
|
|
<entry>Valore predefinito</entry>
|
|
<entry>Valori possibili</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>
|
|
<link linkend="ini.zend.assertions">zend.assertions</link>
|
|
</entry>
|
|
<entry><literal>1</literal></entry>
|
|
<entry>
|
|
<simplelist>
|
|
<member>
|
|
<literal>1</literal>: genera ed esegue il codice (modalità di sviluppo)
|
|
</member>
|
|
<member>
|
|
<!-- TODO: look up the RFC to figure out why you'd want this -->
|
|
<literal>0</literal>: genera il codice ma lo salta in fase di runtime
|
|
</member>
|
|
<member>
|
|
<literal>-1</literal>: non genera il codice (modalità di produzione)
|
|
</member>
|
|
</simplelist>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<link linkend="ini.assert.exception">assert.exception</link>
|
|
</entry>
|
|
<entry><literal>0</literal></entry>
|
|
<entry>
|
|
<simplelist>
|
|
<member>
|
|
<literal>1</literal>: segnala quando l'asserzione fallisce, o
|
|
sollevando l'oggetto fornito come <parameter>exception</parameter>
|
|
o sollevando un nuovo oggetto <classname>AssertionError</classname> se
|
|
<parameter>exception</parameter> non è stato fornito
|
|
</member>
|
|
<member>
|
|
<literal>0</literal>: utilizza o genera un
|
|
<classname>Throwable</classname> come descritto sopra, ma genera
|
|
solo un warning basato su quell'oggetto al posto di sollevarlo
|
|
(compatibile con il comportamento di PHP 5)
|
|
</member>
|
|
</simplelist>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</refsect2>
|
|
</refsect1>
|
|
|
|
<refsect1 role="parameters">
|
|
&reftitle.parameters;
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>assertion</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
L'asserzione. In PHP 5, questo deve essere o una <type>string</type> da
|
|
essere valutata o un <type>boolean</type> da testare. In PHP 7, questo può
|
|
anche essere qualsiasi espressione che restituisce un valore, che verrà eseguita e
|
|
il risultato usato per indicare se l'asserzione è riuscita o meno.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>description</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Una descrizione opzionale che sarà inclusa nel messaggio di fallimento se
|
|
l'<parameter>assertion</parameter> fallisce.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>exception</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
In PHP 7, il secondo parametro può essere un
|
|
oggetto <classname>Throwable</classname> al posto di una <type>string</type>
|
|
descrittiva, nel qual caso questo è l'oggetto che sarà
|
|
sollevato se l'asserzione fallisce e la
|
|
direttiva di configurazione
|
|
<link linkend="ini.assert.exception">assert.exception</link> è abilitata.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="returnvalues">
|
|
&reftitle.returnvalues;
|
|
<para>
|
|
&false; se l'asserzione è false, &true; in caso contrario.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="changelog">
|
|
&reftitle.changelog;
|
|
<para>
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>&Version;</entry>
|
|
<entry>&Description;</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>7.0.0</entry>
|
|
<entry>
|
|
<function>assert</function> è ora un costrutto del linguaggio e non una
|
|
funzione. <function>assertion</function> ora può essere usata come un'espressione.
|
|
Il secondo parametro è ora interpretato o come un
|
|
<parameter>exception</parameter> (se
|
|
viene passato un oggetto<classname>Throwable</classname>), o come la
|
|
<parameter>description</parameter> supportato da PHP 5.4.8 in poi.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>5.4.8</entry>
|
|
<entry>
|
|
È stato aggiunto il parametro <parameter>description</parameter>. La
|
|
<parameter>description</parameter> è anche ora fornita ad una funzione
|
|
di callback in modalità <constant>ASSERT_CALLBACK</constant> come quarto
|
|
parametro.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="examples">
|
|
&reftitle.examples;
|
|
<refsect2>
|
|
<title>Asserzioni tradizionali (PHP 5 e 7)</title>
|
|
<para>
|
|
<example>
|
|
<title>Gestione di un'asserzione fallita con un handler personalizzato</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
// Attiva l'asserzione e la rende silenziosa
|
|
assert_options(ASSERT_ACTIVE, 1);
|
|
assert_options(ASSERT_WARNING, 0);
|
|
assert_options(ASSERT_QUIET_EVAL, 1);
|
|
|
|
// Crea una funzione handler
|
|
function my_assert_handler($file, $line, $code)
|
|
{
|
|
echo "<hr>Assertion Failed:
|
|
File '$file'<br />
|
|
Line '$line'<br />
|
|
Code '$code'<br /><hr />";
|
|
}
|
|
|
|
// Imposta la callback
|
|
assert_options(ASSERT_CALLBACK, 'my_assert_handler');
|
|
|
|
// Fa un'asserzione che dovrebbe fallire
|
|
assert('mysql_query("")');
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title>Uso di un gestore personalizzato per stampare una descrizione</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
// Attiva l'asserzione e la rende silenziosa
|
|
assert_options(ASSERT_ACTIVE, 1);
|
|
assert_options(ASSERT_WARNING, 0);
|
|
assert_options(ASSERT_QUIET_EVAL, 1);
|
|
|
|
// Crea una funzione handler
|
|
function my_assert_handler($file, $line, $code, $desc = null)
|
|
{
|
|
echo "Assertion failed at $file:$line: $code";
|
|
if ($desc) {
|
|
echo ": $desc";
|
|
}
|
|
echo "\n";
|
|
}
|
|
|
|
// Imposta la callback
|
|
assert_options(ASSERT_CALLBACK, 'my_assert_handler');
|
|
|
|
// Fa un'asserzione che dovrebbe fallire
|
|
assert('2 < 1');
|
|
assert('2 < 1', 'Two is less than one');
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs;
|
|
<screen>
|
|
<![CDATA[
|
|
Assertion failed at test.php:21: 2 < 1
|
|
Assertion failed at test.php:22: 2 < 1: Two is less than one
|
|
]]>
|
|
</screen>
|
|
</example>
|
|
</para>
|
|
</refsect2>
|
|
<refsect2>
|
|
<title>Aspettative (solo PHP 7)</title>
|
|
<example>
|
|
<title>Aspettative senza un'eccezione personalizzata</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
assert(true == false);
|
|
echo 'Hi!';
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
Con <link linkend="ini.zend.assertions">zend.assertions</link> impostato a 0,
|
|
l'esempio di sopra stamperà:
|
|
</para>
|
|
<screen>
|
|
<![CDATA[
|
|
Hi!
|
|
]]>
|
|
</screen>
|
|
<para>
|
|
Con <link linkend="ini.zend.assertions">zend.assertions</link> impostato a 1
|
|
e <link linkend="ini.assert.exception">assert.exception</link> impostato a 0,
|
|
l'esempio di sopra stamperà:
|
|
</para>
|
|
<screen>
|
|
<![CDATA[
|
|
Warning: assert(): assert(true == false) failed in - on line 2
|
|
Hi!
|
|
]]>
|
|
</screen>
|
|
<para>
|
|
Con <link linkend="ini.zend.assertions">zend.assertions</link> impostato a 1
|
|
e <link linkend="ini.assert.exception">assert.exception</link> impostato a 1,
|
|
l'esempio di sopra stamperà:
|
|
</para>
|
|
<screen>
|
|
<![CDATA[
|
|
Fatal error: Uncaught AssertionError: assert(true == false) in -:2
|
|
Stack trace:
|
|
#0 -(2): assert(false, 'assert(true == ...')
|
|
#1 {main}
|
|
thrown in - on line 2
|
|
]]>
|
|
</screen>
|
|
</example>
|
|
<example>
|
|
<title>Aspettative con un'eccezione personalizzata</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
class CustomError extends AssertionError {}
|
|
|
|
assert(true == false, new CustomError('True is not false!'));
|
|
echo 'Hi!';
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
Con <link linkend="ini.zend.assertions">zend.assertions</link> impostato a 0,
|
|
l'esempio di sopra stamperà:
|
|
</para>
|
|
<screen>
|
|
<![CDATA[
|
|
Hi!
|
|
]]>
|
|
</screen>
|
|
<para>
|
|
Con <link linkend="ini.zend.assertions">zend.assertions</link> impostato a 1
|
|
e <link linkend="ini.assert.exception">assert.exception</link> impostato a 0,
|
|
l'esempio di sopra stamperà:
|
|
</para>
|
|
<screen>
|
|
<![CDATA[
|
|
Warning: assert(): CustomError: True is not false! in -:4
|
|
Stack trace:
|
|
#0 {main} failed in - on line 4
|
|
Hi!
|
|
]]>
|
|
</screen>
|
|
<para>
|
|
Con <link linkend="ini.zend.assertions">zend.assertions</link> impostato a 1
|
|
e <link linkend="ini.assert.exception">assert.exception</link> impostato a 1,
|
|
l'esempio di sopra stamperà:
|
|
</para>
|
|
<screen>
|
|
<![CDATA[
|
|
Fatal error: Uncaught CustomError: True is not false! in -:4
|
|
Stack trace:
|
|
#0 {main}
|
|
thrown in - on line 4
|
|
]]>
|
|
</screen>
|
|
</example>
|
|
</refsect2>
|
|
</refsect1>
|
|
|
|
<refsect1 role="seealso">
|
|
&reftitle.seealso;
|
|
<para>
|
|
<simplelist>
|
|
<member><function>assert_options</function></member>
|
|
</simplelist>
|
|
</para>
|
|
</refsect1>
|
|
|
|
</refentry>
|
|
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-omittag:t
|
|
sgml-shorttag:t
|
|
sgml-minimize-attributes:nil
|
|
sgml-always-quote-attributes:t
|
|
sgml-indent-step:1
|
|
sgml-indent-data:t
|
|
indent-tabs-mode:nil
|
|
sgml-parent-document:nil
|
|
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:nil
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
vim600: syn=xml fen fdm=syntax fdl=2 si
|
|
vim: et tw=78 syn=sgml
|
|
vi: ts=1 sw=1
|
|
-->
|