mirror of
https://github.com/php/doc-ja.git
synced 2026-03-27 08:32:09 +01:00
a3c9dfdc76
原文: Declaring a function called assert() inside a namespace is no longer allowed, and issues E_COMPILE_ERROR. そもそも PHP は C言語 のように関数の宣言と定義の区別はないはずなのです。しかし、英語版のマニュアルでは 宣言(declare) と 定義(define) が関数の文脈で混在しています。 それらの区別を知っている人からしてみれば、それはとてもモヤっとする記述です。ですが、関数については英語版に合わせる方針がこれまでも取られてきており、このコミットでもそれに合わせた修正をしています。
487 lines
17 KiB
XML
487 lines
17 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!-- $Revision$ -->
|
|
<!-- EN-Revision: 59af09939ab6e191c9836ea3b33b934e1a99a263 Maintainer: hirokawa Status: ready -->
|
|
<!-- CREDITS: takagi,mumumu -->
|
|
<refentry xml:id="function.assert" xmlns="http://docbook.org/ns/docbook">
|
|
<refnamediv>
|
|
<refname>assert</refname>
|
|
<refpurpose>assertion が &false; であるかどうかを調べる</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsect1 role="description">
|
|
&reftitle.description;
|
|
<para>PHP 5 および PHP 7</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> は、指定した
|
|
<parameter>assertion</parameter> を調べて、結果が
|
|
&false; の場合に適切な動作をします。
|
|
</para>
|
|
<refsect2>
|
|
<title>従来のアサーション (PHP 5 および 7)</title>
|
|
<para>
|
|
<parameter>assertion</parameter> が文字列として指定された場合、
|
|
<function>assert</function>によりPHPコードとして評価されます。
|
|
もし論理型の条件を <parameter>assertion</parameter> として渡した場合、
|
|
<function>assert_options</function> 関数で定義したであろう
|
|
アサーション関数への引数として表示されません。
|
|
その条件はハンドラ関数をコールする前に文字列に変換され、論理型の
|
|
&false; は空文字列に変換されます。
|
|
</para>
|
|
<para>
|
|
assertion は、デバッグ目的にのみ使用するべきです。
|
|
assertion を常に&true;となる条件を調べる不具合診断に使用し、&true;
|
|
でない場合に何らかのプログラミングエラーを示したり、extension
|
|
関数または特定のシステム制限や機能といった、
|
|
特定の機能の存在をチェックするために使用することが可能です。
|
|
</para>
|
|
<para>
|
|
assersion は、入力パラメータのチェックのような通常の実行動作に
|
|
使用するべきではありません。一般的には、assertion のチェックを無効にしても
|
|
そのコードが正常に動作しなければなりません。
|
|
</para>
|
|
<para>
|
|
<function>assert</function> の動作は、
|
|
<function>assert_options</function> またはマニュアルの関数の部分
|
|
に記述された .ini の設定により設定することが可能です。
|
|
</para>
|
|
<para>
|
|
関数 <function>assert_options</function> や
|
|
<constant>ASSERT_CALLBACK</constant> 設定ディレクティブにより失敗した assertion
|
|
を処理するコールバック関数を設定することが可能です。
|
|
</para>
|
|
<para>
|
|
<function>assert</function> のコールバックは、assertion
|
|
が発生した場所に関する情報と共に assertion
|
|
に渡されたコードを容易にキャプチャーできるため、
|
|
特に自動テストセットを構築する際に便利です。
|
|
この情報は他の手法でもキャプチャー可能ですが、assertion
|
|
を使用することにより、より簡単かつ容易に行なうことが可能です!
|
|
</para>
|
|
<para>
|
|
コールバック関数は、3つの引数を受ける必要があります。最初の引数は、
|
|
assertionが失敗したファイルが含まれます。2番目の引数には、
|
|
assertionが失敗した行が含まれ、3番目の引数には失敗した式が含まれます
|
|
(もしある場合のみ。1 または "two" のようなリテラルの値は、
|
|
この引数に渡されません)。
|
|
PHP 5.4.8 以降では、オプションの4番目の引数を指定できます。これを設定すると、
|
|
<parameter>description</parameter> を <function>assert</function>
|
|
に渡せるようになります。
|
|
</para>
|
|
</refsect2>
|
|
<refsect2 xml:id="function.assert.expectations">
|
|
<title>Expectation (PHP 7 のみ)</title>
|
|
<para>
|
|
<function>assert</function> は PHP 7 で言語構造となり、expectation の定義を満たすようになりました。
|
|
すなわち、開発環境やテスト環境では有効であるが、運用環境では除去されて、まったくコストのかからないアサーションということです。
|
|
</para>
|
|
<para>
|
|
下位互換性を保つために、<function>assert_options</function> でこれらの挙動を制御することもできますが、
|
|
PHP 7 以降でしか使わないコードでは、新たに導入された二つの設定ディレクティブを使って
|
|
<function>assert</function> の挙動を制御しましょう。
|
|
そして <function>assert_options</function> は使わないようにしましょう。
|
|
</para>
|
|
<table>
|
|
<title>
|
|
PHP 7 における <function>assert</function> 用の設定ディレクティブ
|
|
</title>
|
|
<tgroup cols="3">
|
|
<thead>
|
|
<row>
|
|
<entry>ディレクティブ</entry>
|
|
<entry>デフォルト値</entry>
|
|
<entry>取り得る値</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>: コードを生成して実行する (開発モード)
|
|
</member>
|
|
<member>
|
|
<!-- TODO: look up the RFC to figure out why you'd want this -->
|
|
<literal>0</literal>: コードを生成するが、実行時には読み飛ばす
|
|
</member>
|
|
<member>
|
|
<literal>-1</literal>: コードを生成しない (運用モード)
|
|
</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>: アサーションに失敗した場合には、
|
|
<parameter>exception</parameter> で指定したオブジェクトをスローするか、
|
|
<parameter>exception</parameter> を指定していない場合は
|
|
<classname>AssertionError</classname> オブジェクトをスローします。
|
|
</member>
|
|
<member>
|
|
<literal>0</literal>: 先述の
|
|
<classname>Throwable</classname> を使ったり生成したりしますが、
|
|
そのオブジェクト上で警告を生成するだけであり、スローしません
|
|
(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>
|
|
アサーション。
|
|
PHP 5 では、評価対象の文字列か、あるいは
|
|
<type>bool</type> 値しか指定できませんでした。
|
|
PHP 7 ではそれ以外にも、値を返すあらゆる式を指定できます。
|
|
この式を実行した結果を用いて、アサーションに成功したか否かを判断します。
|
|
</para>
|
|
<warning>
|
|
<para>
|
|
<parameter>assertion</parameter> に <type>string</type> を使うのは
|
|
PHP 7.2.0 以降は <emphasis>推奨されなくなりました</emphasis>。
|
|
PHP 8.0.0 以降では <emphasis>削除されています</emphasis>。
|
|
</para>
|
|
</warning>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>description</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
オプションの説明です。
|
|
<parameter>assertion</parameter> が失敗したときのメッセージを設定します。
|
|
PHP 7 からは、この説明が指定されない場合、
|
|
<function>assert</function> を呼び出したソースコードに関するデフォルトの説明が設定されます。
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>exception</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
PHP 7 では、第二パラメータに、文字列だけではなく
|
|
<classname>Throwable</classname> オブジェクトを指定できるようになりました。
|
|
これを指定した場合は、
|
|
<link linkend="ini.assert.exception">assert.exception</link> が有効で
|
|
かつアサーションに失敗した場合に、そのオブジェクトをスローします。
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="returnvalues">
|
|
&reftitle.returnvalues;
|
|
<para>
|
|
アサーションが false となった場合に &false;、それ以外の場合に &true; を返します。
|
|
</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>8.0.0</entry>
|
|
<entry>
|
|
<function>assert</function> は、
|
|
文字列の引数を評価しなくなりました。
|
|
代わりに、他の引数と同じ扱いをされるようになっています。
|
|
<code>assert('$a == $b')</code> ではなく、
|
|
<code>assert($a == $b)</code> を使うべきです。
|
|
&php.ini; ディレクティブ
|
|
<literal>assert.quiet_eval</literal> と
|
|
<constant>ASSERT_QUIET_EVAL</constant>
|
|
も削除されており、それらを使っても何も起きなくなっています。
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>8.0.0</entry>
|
|
<entry>
|
|
名前空間の内部で、
|
|
<literal>assert()</literal> という名前の関数を宣言することはできなくなりました。
|
|
宣言した場合、<constant>E_COMPILE_ERROR</constant> が発生します。
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>7.3.0</entry>
|
|
<entry>
|
|
名前空間の内部で、
|
|
<literal>assert()</literal> という名前の関数を宣言することは推奨されなくなりました。
|
|
宣言した場合、
|
|
<constant>E_DEPRECATED</constant> が発生するようになっています。
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>7.2.0</entry>
|
|
<entry>
|
|
<parameter>assertion</parameter> に <type>string</type> を使うことは
|
|
推奨されなくなりました。
|
|
<link linkend="ini.assert.active">assert.active</link>
|
|
と <link linkend="ini.zend.assertions">zend.assertions</link> が
|
|
両方 <literal>1</literal> に設定されると、
|
|
<constant>E_DEPRECATED</constant> レベルの警告が発生するようになりました。
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>7.0.0</entry>
|
|
<entry>
|
|
<function>assert</function> が言語構造となり、関数ではなくなりました。
|
|
<parameter>assertion</parameter> に式を指定できるようになりました。
|
|
第二パラメータは、
|
|
<parameter>exception</parameter> (<classname>Throwable</classname> オブジェクトを渡した場合)
|
|
あるいは
|
|
<parameter>description</parameter> (PHP 5.4.8 以降でサポートされていたもの)
|
|
のいずれかであると解釈されるようになりました。
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="examples">
|
|
&reftitle.examples;
|
|
<refsect2>
|
|
<title>従来のアサーション (PHP 5 および 7)</title>
|
|
<para>
|
|
<example>
|
|
<title>失敗した assertion をカスタムハンドラで処理する</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
// assertを有効にし、出力を抑制する
|
|
assert_options(ASSERT_ACTIVE, 1);
|
|
assert_options(ASSERT_WARNING, 0);
|
|
assert_options(ASSERT_QUIET_EVAL, 1);
|
|
|
|
// ハンドラ関数を作成する
|
|
function my_assert_handler($file, $line, $code)
|
|
{
|
|
echo "<hr>Assertion Failed:
|
|
File '$file'<br />
|
|
Line '$line'<br />
|
|
Code '$code'<br /><hr />";
|
|
}
|
|
|
|
// コールバックを設定する
|
|
assert_options(ASSERT_CALLBACK, 'my_assert_handler');
|
|
|
|
// 失敗するassertionを作成
|
|
assert('mysql_query("")');
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title>カスタムハンドラを使った説明の表示</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
// assertを有効にし、出力を抑制する
|
|
assert_options(ASSERT_ACTIVE, 1);
|
|
assert_options(ASSERT_WARNING, 0);
|
|
assert_options(ASSERT_QUIET_EVAL, 1);
|
|
|
|
// ハンドラ関数を作成する
|
|
function my_assert_handler($file, $line, $code, $desc = null)
|
|
{
|
|
echo "Assertion failed at $file:$line: $code";
|
|
if ($desc) {
|
|
echo ": $desc";
|
|
}
|
|
echo "\n";
|
|
}
|
|
|
|
// コールバックを設定する
|
|
assert_options(ASSERT_CALLBACK, 'my_assert_handler');
|
|
|
|
// 失敗するassertionを作成
|
|
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>Expectation (PHP 7 のみ)</title>
|
|
<example>
|
|
<title>自作の例外を指定しない expectation</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
assert(true == false);
|
|
echo 'Hi!';
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
<link linkend="ini.zend.assertions">zend.assertions</link> が 0
|
|
の場合は、上の例の結果は次のようになります。
|
|
</para>
|
|
<screen>
|
|
<![CDATA[
|
|
Hi!
|
|
]]>
|
|
</screen>
|
|
<para>
|
|
<link linkend="ini.zend.assertions">zend.assertions</link> が 1、かつ
|
|
<link linkend="ini.assert.exception">assert.exception</link> が 0
|
|
の場合は、上の例の結果は次のようになります。
|
|
</para>
|
|
<screen>
|
|
<![CDATA[
|
|
Warning: assert(): assert(true == false) failed in - on line 2
|
|
Hi!
|
|
]]>
|
|
</screen>
|
|
<para>
|
|
<link linkend="ini.zend.assertions">zend.assertions</link> が 1、かつ
|
|
<link linkend="ini.assert.exception">assert.exception</link> が 1
|
|
の場合は、上の例の結果は次のようになります。
|
|
</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>自作の例外を用いた expectation</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
class CustomError extends AssertionError {}
|
|
|
|
assert(true == false, new CustomError('True is not false!'));
|
|
echo 'Hi!';
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
<link linkend="ini.zend.assertions">zend.assertions</link> が 0
|
|
の場合は、上の例の結果は次のようになります。
|
|
</para>
|
|
<screen>
|
|
<![CDATA[
|
|
Hi!
|
|
]]>
|
|
</screen>
|
|
<para>
|
|
<link linkend="ini.zend.assertions">zend.assertions</link> が 1、かつ
|
|
<link linkend="ini.assert.exception">assert.exception</link> が 0
|
|
の場合は、上の例の結果は次のようになります。
|
|
</para>
|
|
<screen>
|
|
<![CDATA[
|
|
Warning: assert(): CustomError: True is not false! in -:4
|
|
Stack trace:
|
|
#0 {main} failed in - on line 4
|
|
Hi!
|
|
]]>
|
|
</screen>
|
|
<para>
|
|
<link linkend="ini.zend.assertions">zend.assertions</link> が 1、かつ
|
|
<link linkend="ini.assert.exception">assert.exception</link> が 1
|
|
の場合は、上の例の結果は次のようになります。
|
|
</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
|
|
-->
|