Bitrix Framework

The new core uses the mechanism of exceptions.

Examples

If a user has sent a form with an empty Name field, it is not an exception case. It is a regular expected case that must be handled appropriately.

But if in case of API method invocation in order to change an infoblock element an empty element id was specified, it is an exception case. It is unexpected and it makes no sense to continue changing the element.

If the method is waiting for the user id and you transmit a line, it is an exception, because the method does not know what to do with the line in this case.

If the GetList method accepts the timestamp filter, and developer has written “tymestamp,” it will be an exception.

Exception Hierarchy

Available exceptions have a hierarchy. It handles exceptions, shows the activated exceptions, which allows to take appropriate actions. The general hierarchy logic is as follows:

\Exception
   Bitrix\Main\SystemException         - basic class of all system exceptions
      Bitrix\Main\IO\IoException         - basic class of all exceptions of file input-output
         Bitrix\Main\IO\FileDeleteException   - exception in case of file deletion
         Bitrix\Main\IO\FileNotFoundException   - absence of a required file
         Bitrix\Main\IO\FileOpenException   - exception in case of file opening
         Bitrix\Main\IO\InvalidPathException   - invalid path
         Bitrix\Main\IO\FileNotOpenedException - file not opened 
      Bitrix\Main\Config\ConfigurationException   - configuration error
      Bitrix\Main\Security\SecurityException      - security error
      Bitrix\Main\Security\Sign\BadSignatureException  - signature error exception.
      Bitrix\Main\ArgumentException      - basic class of exceptions associated with incoming parameters of methods
         Bitrix\Main\ArgumentNullException   - parameter must not be left empty
         Bitrix\Main\ArgumentOutOfRangeException   - parameter outside a permitted range
         Bitrix\Main\ArgumentTypeException   - inadmissible type parameter
      Bitrix\Main\DB\DbException      - basic class for database exceptions
         Bitrix\Main\DB\ConnectionException   - exception during connection
         Bitrix\Main\DB\SqlException      - exception during performance of a query
      Bitrix\Main\NotSupportedException   - is invoked if the functionality is not supported
      Bitrix\Main\NotImplementedException   - is invoked if the functionality must be supported but is not implemented so far
 Bitrix\Main\ObjectPropertyException - is invoked when the object properties are invalid
 Bitrix\Main\ObjectNotFoundException - is invoked when object does not exist 
 Bitrix\Main\ObjectException - is invoked if object cannot be created.  
 Bitrix\Main\LoaderException      - exception in loader

Bitrix\Main\SystemException is the basic class for all system exceptions; all the rest of exceptions are inherited from it. This class re-defines the constructor for the \Exception system class. If the system class receives the message and error code on input:

<?php
public function __construct($message = null, $code = 0, Exception $previous = null);

the constructor Main\SystemException additionally receives the file with a thrown exception and a number of string:

<?php
public function __construct($message = "", $code = 0, $file = "", $line = 0, \Exception $previous = null);

Thrown exception must have the most suitable type possible.

If your method creates an exception, it must be described in the method phpDoc.

In Bitrix Framework, it is done as follows:

 /**
     * Searches connection parameters (type, host, db, login and password) by connection name
     *
     * @param string $name Connection name
     * @return array|null
     * @throws \Bitrix\Main\ArgumentTypeException
     * @throws \Bitrix\Main\ArgumentNullException
     */
    protected function getConnectionParameters($name) {}

Ignoring exceptions

Sometimes, an occurred error must not interrupt execution of a script. Such situation can be exemplified by the operation of CDN module administration page.

If the CDN module is enabled, the traffic data is displayed at the top of the page. Its code looks as follows:

$cdn_config = CBitrixCloudCDNConfig::getInstance()->loadFromOptions();
$APPLICATION->SetTitle(GetMessage("BCL_TITLE"));
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/modules/main/include/prolog_admin_after.php");
if (is_object($message))
	echo $message->Show();

if (CBitrixCloudCDN::IsActive())
{
	try
	{
		if ($cdn_config->getQuota()->isExpired())
			$cdn_config->updateQuota();

		$cdn_quota = $cdn_config->getQuota();
		if ($cdn_quota->getAllowedSize() > 0.0 || $cdn_quota->getTrafficSize() > 0.0)
		{
			CAdminMessage::ShowMessage(array(
				"TYPE" => "PROGRESS",
				"DETAILS" => '
'.GetMessage("BCL_CDN_USAGE", array(
					"#TRAFFIC#" => CFile::FormatSize($cdn_quota->getTrafficSize()),
					"#ALLOWED#" => CFile::FormatSize($cdn_quota->getAllowedSize()),
				)).'
#PROGRESS_BAR#',
				"HTML" => true,
				"PROGRESS_TOTAL" => $cdn_quota->getAllowedSize(),
				"PROGRESS_VALUE" => $cdn_quota->getTrafficSize(),
			));
		}
	}
	catch (Exception $e)
	{
		CAdminMessage::ShowMessage($e->getMessage());
	}
}

The code above shows that if CDN is active, the progress bar with the displayed traffic data is created. However, if an error occurs during execution of this code, an exception will be thrown. This exception will be caught, because all the code is located in try and the branch will be executed after catch, where the error message is displayed via the standard function. The script execution will not be interrupted.