Утверждения (assertions)

Query Monitor

С версии 3.15, Query Monitor позволяет разработчикам выполнять проверки, которые создадут запись об ошибке в панели Query Monitor "Логи (Logs)", если проверка не пройдена.

Это удобная обертка для логирования ошибок, которая будет оповещать вас о проблемах в коде.

Пример, того как это выглядит:

Эта функциональность доступна с версии Query Monitor 3.15.

Использование

do_action( 'qm/assert', $value === 5 );
do_action( 'qm/assert', $value === 5, 'Value is 5' );
do_action( 'qm/assert', $value === 5, 'Value is 5', $value );

Если проверка провалилась, Query Monitor покажет ошибку в панели (панель при этом будет подсвечена красным), это позволит сразу обратить внимание на ошибку. Если проверка прошла успешно, то в панели будет сообщение уровня отладки, это поможет убедиться, что проверка есть и она прошла.

Первый параметр события qm/assert - это сама проверка, как правило, нужно указывать PHP выражение, которое должно вернуть truthy/falsy значение.

Второй параметр - это необязательное краткое описание проверки. Если параметр предоставлен, он будет отображаться вместе с сообщением об ошибке или успешном прохождении проверки.

Третий параметр - это необязательное значение любого типа, которое будет выводиться под сообщением об ошибке при провале проверки. Это полезно для отладки неожиданного значения.

Не регистрируйте большие значения, например массив объектов постов или ответ от HTTP-запроса. Если нужно отладить значение чего-то большого, используйте другой инструмент, например Xdebug или Ray.

Примеры использования

Это событие можно использовать для контроля корректности работы кода, например, для проверки количества выполненных или невыполненных запросов к базе данных:

foreach ( $posts as $post ) {
	$before = $wpdb->num_queries;
	$this->process_post( $post );
	$after = $wpdb->num_queries;

	// Assert that no database queries are performed as we process each post:
	do_action( 'qm/assert', $after === $before );
}

Предусловия можно использовать для проверки определенного состояния перед выполнением логики на основе ожиданий:

do_action( 'qm/assert', is_array( $data ), 'Data is an array', $data );
do_action( 'qm/assert', array_key_exists( 'foo', $data ), 'Data contains foo', $data );

Постусловия можно использовать для проверки наличия определенного результата:

do_action( 'qm/assert', did_action( 'my-action' ) );

Статический метод проверки на классе QM может быть использован вместо вызова do_action():

QM::assert( $value === 5 );
QM::assert( $value === 5, 'Value is 5' );
QM::assert( $value === 5, 'Value is 5', $value );

Однако в этом случае при отключении плагина QM вы получите фатальную ошибку.

Различия от assert()

Эта функция отличается от встроенной функции assert() в PHP, так как они служат разным целям.

  • Функция PHP assert() в PHP прекращает выполнение скрипта, если проверка не удалась, Query Monitor этого не делает. Считайте это "мягкой" проверкой, которая выдает ошибку вместо прекращения работы. Код должен работать как ожидается, независимо от того, прошла ли проверка.

  • Query Monitor также регистрирует успешные проверки. Это полезно для проверки того, что ваша проверка выполняется.

  • Проверки в Query Monitor всегда выполняются и записываются при необходимости. Функция assert() в PHP будет выполнять проверку только в том случае, если проверки включены в настройке php.ini.

  • В проверки Query Monitor можно передать необязательное значение для вывода в целях отладки, что невозможно сделать с assert().

Примечания по использованию

Проверки представляют собой в основном инструмент разработки для выявления ошибок или неоптимальной работы вашего кода. Это отличается от обработки ошибок или проверки данных, на что проверки не предназначены.

Так же, как и с функцией assert() в PHP, ваш код должен обрабатывать ситуацию, когда ваша проверка не пройдена, потому что в рабочей среде код будет продолжать выполняться после проверки.