What are common Best Practices and Gotchas to consider when using the Connect for PHP (CPHP) API?

Environment:

Oracle B2C Service, Product listing
Connect for PHP (CPHP) API

Resolution:

Use latest framework version

Using the latest CPHP framework version is recommended for all new customizations and if possible otherwise. Doing so is the best option to avoid encountering product defects.

PHP try/catch

Handle expected and possible errors with try/catch statements. Scripts should catch generic PHP and Connect for PHP exception types and should log/output/email errors to an accessible location. For details on this see

Answer ID 9897:  Adding custom logging to your customizations

The value of catching exceptions in code is that the related software can "fail gracefully", with the ability to log/notify on the error, and then allow processing to continue rather than the software just failing (which is what happens when an uncaught exception happens in general).

try 
{
.
.
.
}
catch (RNCPHP\ConnectAPIError $err)
{
    // output $err->getMessage()
}
catch(\Exception $err) 
{
    // output $err->getMessage()
}

PHP try/catch for CPM customizations

Special considerations for CPM script error handling should be considered. PHP echo can be used to output information to the Process Designer error log. Also, asynchronous CPMs can ensure that failed CPMs are re-run by throwing a new unhandled exception from within the catch block. For further details on this see

Answer ID 6607: Asynchronous CPM processes queued are removed automatically after five unsuccessful tries

try 
{
.
.
.
}
catch (RNCPHP\ConnectAPIError $err)
{
    // output $err->getMessage()
    echo $err->getMessage();
    throw new \Exception("Throwing manual exception after caught exception");
}
catch(\Exception $err) 
{
    // output $err->getMessage()
    echo $err->getMessage();
    throw new \Exception("Throwing manual exception after caught exception");
}

API save

Avoid redundant API saves within code as each one adds overhead to script processing. It is also important to ensure that API suppression is used correctly when API saves are used on a site that runs CPM customizations. For details see

Answer ID 7890: Enabling API suppression in Connect for PHP Customizations

$obj->save();

API commit

Only use the API commit statement if necessary for specific situations. API commit is implied, that is it automatically happens when an API save is run within code as CPHP customized script is finished running. Running API commits within code add overhead to customization processing. If API commits are used in code then keep them to a minimum.

RNCPHP\ConnectAPI::commit();

Please note—a specific situation where committing is strongly recommended as a best practice is before any cURL call, since these can take some time. This is especially relevant with the Knowledge Advanced REST API, since it uses the same database as the Connect APIs and a pending transaction may cause the very call being made to have to wait until your script's call to it times out. For example, end-user userToken generation requires validation against the contact record; if that contact record has been saved in an open Connect PHP transaction, the userToken will not be generated until after the CURL_OPT_TIMEOUT_LIMIT is reached and the transaction is committed or rolled back. That is, your script will have given up on getting the token, and if that causes a failure there will be no implied commit.

PHP is_writeable

When using PHP is_writeable you must use a trailing slash to identify a directory, such as in the following example (notice the trailing slash in bold):

<?php
  $dir = '/tmp/';
  if (is_writable($dir)) {
    echo $dir, ' is writable';
  } else {
    echo $dir, ' is NOT writable';
  }
?>

Failure to use the trailing slash will result in is_writeable throwing an exception indicating "Access to is_writeable is denied because its trying to access restricted folders".

PHP empty

The PHP empty function is useful for checking that a variable holds a value before using in an assignment, such as in the following example:

<?php
  if (empty($var)) {
    echo '$var is either 0, empty, or not set at all';
  }
?>